By dave | November 13, 2016
In this article I discuss moving sites from Joomla over to Hugo static content manager. Before we start lets take a quick look at why we may want to do this, and the cases were it may not be appropriate.
tl;dr: In summary, hosting a site on Joomla is time consuming and requires that both Joomla and PHP are frequently updated. If you’re site is suitable for Hugo and are considering moving over, take a look through the phases below.
Static content management compiles the entire site from a series of mark down files stored away from the main site. In order to change the site one must rebuild the site and redeploy. This can be made simple enough that a non developer can easily perform the task, in fact there are now even both client side Java applications and web front ends that can work with hugo.
If your site is mainly static pages that need editing then you may find that a static content manager is a better fit, as it has several advantages including reduced hosting footprint and there is no database and server scripting to manage. Also, very a very important security step up over PHP is that the source of the site is separate and very easy to store the site in a source control system such as git or svn.
IMHO even if your site is partially dynamic, I’d want to move the dynamic part away from the static part keeping the attack vectors as small as possible. Most people at some point or other forget to apply updates for PHP or Joomla; this is especially important when using WordPress or Joomla to do so as hackers are constantly looking for flaws in them. Further, they rely on a large number of sites not being frequently updated and therefore easily hacked. Static systems such as Hugo don’t have anywhere near as many moving parts and only the server need be updated frequently.
If you need more background to help you decide if the switch is right for you, I’ve linked some articles that helped me decide on using a static CMS: Discussion about using Hugo
Phase 1 - planning the move
At this point I assume you’ve decided as I did to go for Hugo. So you are probably the administrator of a Joomla site. Before proceeding check that you:
- are already using the SEO friendly URL option, if not it will not be an automatic process.
- can get access to the mysql database so that the conversion utility can obtain the content.
- go through all the important links within your site and ensure they can be mapped statically or prepare redirects.
- write down where all the static content lives on the site (eg images, file downloads etc) to prepare it for the move.
Phase 2 - getting hugo running with the Joomla articles
Before anything else you’ll need to build a new hugo site and choose a suitable template. For this I recommend the Hugo quick start guide that should get you started. Choose a suitable template and create a few test pages. At this point you should have a site with a template that renders the test pages.
Now if you are on a recent version of Joomla (more or less anything from V3 onwards) then you can use the Joomla to Hugo conversion tool to migrate the content data. Joomla to Hugo conversion tool. The usage of this is fully documented on the github page, after running the tool you should have most of the content that was in Joomla available in Hugo. This will include Tags, Categories and Content. You will need to remove the parent from the top level categories. As they should not be present. It’s not possible for the tool to do this, as the name of the top level can be different depending on version.
At this point copy all of the static content into the static folder. As long as your images were in the images directory then any links to them should have been modified.
Phase 3 - modifying the template to work with the content
Now it’s time to try and use this content with your template, if you use the universal template it will partially work out of the box as it uses the right content types for this template. By default all content pages will be of type “blog” and all category pages of type “category”, you may need to alter this for your template.
During the conversion, the tool generated a top level entry for every category. Each category
will have a page associated with it at the appropriate level in the tree. If like me, you used
nested categories, you will probably need to add a layout directory
category with a template
single.html that renders the entries within the category and it’s children. The joomla
conversion tool uses the same conventions as the following site:
Nested structure in Hugo.
You may also want a list of all tags, if you do, add a terms.html to the default directory following the examples on the hugo site.
Phase 4 - deploying the tested version to production
Setting the 404 error handler page
In either your .htaccess or apache configuration file you’ll need to set the error handler for the 404 page. The templates I’ve looked at have a suitable 404 page for starters, but maybe you should consider improving it to have the menu structure within it, as people often hit that page when something has moved. For example with the VirtualHost / Directory settings:
ErrorDocument 404 /404.html
Redirecting any pages that you cannot directly map to hugo
For each page that you cannot map directly, you will have to place redirects in the same files as above for them. There’s a lot of documentation about this on the web. I’d start here Apache mod-rewrite guide. At this point you can also take the opportunity to clean up the htaccess file.
Deploying to live
Choose the time when your audience least uses your site and make a full backup of the web directory. Preferably by zipping it up to ensure it can be put back in place if needed. Only once the back up is done would I even attempt to replace the site files with the new Hugo site that you’ve tested fully locally.
Now carefully check your most important links, the ones that come in from search engines are working properly. These are the links that google search console (previously webmaster tools) shows. If these links are not working, rollback and fix locally.
It’s inevitable that there will be some unmapped files, Joomla unfortunately allows links into the site from many different URL formats without redirecting to a standard format. Use google webmaster tools to fix as many as you can practically.