Transferring the Content
The most challenging part of any migration is extracting the content from the existing site and getting it presentable in a format the new site can use. Thankfully, with Hugo’s rising popularity, there are a few tools and scripts available that handle a lot of the heavy lifting for you. But how you do it depends on which platform you’re migrating from.
If you’re migrating from a WordPress blog, you can use the WordPress-to-Hugo Export plugin.[59] This plugin exports all of your content, placing each post in its own Markdown file. The plugin preserves the original post’s permalink, and places it in the front matter section of the corresponding Markdown file. It also stores the draft status.
If you have a self-hosted WordPress installation, you can install the WordPress-to-Hugo Export plugin and use it from within the WordPress user interface. Download the plugin, extract it, and upload it to your server via SFTP or SCP into your site’s /wp-content/plugins/ directory. Then, visit your site, log in as an admin, and select Export to Hugo from the Tools menu.
If your WordPress site is hosted on WordPress.com, or you don’t have direct access to the server, things will be more difficult. You’ll need to set up a local WordPress instance, export the data from your existing site as an XML file, import your data into your local WordPress instance, and then install and use the plugin.
If you’re using Jekyll as your current platform, Hugo has a built-in command to migrate your content. Ensure you have all of the source files for your Jekyll site and use the following command to convert your content:
| | $ hugo import jekyll jekyll_root_path target_path |
If you’re using Ghost, Tumblr, or other platforms, Hugo has a list of tools and scripts[60] you can use to help you get your content out.
Whichever method you use to migrate your content, remember that search engines and other sites may be pointing to your content, so you want to make sure that those links still work after your migration. Use the url field in front matter to specify the URL you want to use, or configure your web server to redirect visitors to the new URLs. If you’re using Netlify, you can use their support for redirects.[61]
Automated scripts will get you about 80% of the way there. Depending on how your original system stored your content, the translation to Markdown might not be as smooth as you’d hoped. Many of the conversion utilities attempt to convert HTML content to Markdown. If your content has HTML that can’t be converted, the conversion process might leave the HTML alone, leaving you with a mix of HTML and Markdown. Hugo’s Markdown renderer will ignore HTML and JavaScript in Markdown documents. You may have to manually clean up the content yourself file by file. It can be a chore, but if you take the time to do that cleanup, all of your content will be clean, in plain-text Markdown documents, and will be much easier to manage going forward.
If you have some complex HTML in your content, and you can’t figure out how to convert it, or don’t like the results, you can configure Hugo’s Markdown renderer to operate in “unsafe” mode, which will allow Hugo to render the HTML fragments. Add the following code to your config.toml file:
| | [markup] |
| | [markup.goldmark] |
| | [markup.goldmark.renderer] |
| | unsafe = true |
This will let you get more of your content migrated, but it does open a potential security hole that would allow unsafe code to run. For example, if you’d migrated some code from a WordPress site, and one of your pages had some malicious JavaScript code on it that you didn’t notice, Hugo’s defaults would prevent that malicious code from rendering. So, before turning this on, triple-check your content.
If you’re not willing to do all of that cleanup work, you have two options: you can leave your content as-is and fix it over time, or you can unpublish the content.
To unpublish content, do a global search and replace and set the draft status of everything before a certain date to true, so it will no longer be published. When you put things in a draft status, you can update them over time, and reactivate them when you’re ready. This will likely break external links to your content, so be mindful of that. As an alternative, you can add a new field to your front matter and modify your template to show a deprecation notice or other disclaimer for pages with that field.
Your pages and posts aren’t the only bits of content you’ll need to think about.
Handling Comments
If you have a vibrant community of people sharing their thoughts and opinions on your content, you will likely want to keep that content on your new site as well.
The best approach to keep your comments is to migrate them to Disqus directly when possible. Disqus has guides for importing comments[62] that you can refer to for help with this process.
Some of the export scripts can preserve comments as well. You can then freeze those old comments on those posts to prevent future commenting.
You might consider a combination of these approaches too. For example, you might migrate your most recent posts’ comments to Disqus, while treating anything over a year old as an archive.
Handling Images and Other Assets
Images need to be migrated from your old site to your new site, just like content, and how you migrate them depends entirely on how your images were linked to your content. If you hosted your images on an asset server with absolute links, then there’s nothing you’ll need to do, as the links will still work. If your site images were uploaded through your CMS, the links in the content pages may need some updates depending on where those images are located now.
The WordPress export plugin for Hugo places all of the images in the static folder. If you have a lot of images, this can get messy. You may want to spend some time organizing the content and updating any image references.
If you were using an image gallery plugin that relies on server-side processing, like one written in PHP, it won’t work with a Hugo site. You could use a JavaScript-based library, but you can also create your own image gallery using a Hugo shortcode that reads files from your static folder and constructs a link and image for each one.
Create a file in your theme named shortcodes/gallery.html with the following contents:
| | {{ $path := .Get 0 }} |
| | {{ $files := readDir (print "/static/" $path) }} |
| | |
| | <div class="gallery"> |
| | {{ range $files }} |
| | <a href="{{ $path }}/{{ .Name }}"> |
| | <img src="{{ $path }}/{{ .Name }}"> |
| | </a> |
| | {{ end }} |
| | </div> |
This fetches all files from a given directory, iterates over each one, and displays them on the page.
You can then add some CSS to style each image in the gallery:
| | .gallery img { |
| | margin: 1em; |
| | height: 240px; |
| | width: 320px; |
| | } |
Invoke the gallery by adding the shortcode to a content page:
| | {{< gallery "/images/vacation-photos" >}} |
In this example, the gallery displays all the images located in static/images/vacation-photos.
This approach uses CSS to resize the images, which isn’t ideal. You could use what you learned in Using a Shortcode to Process Images to build a more robust version of this that reads images from a page bundle and resizes them, creating smaller thumbnails.
You can use custom shortcodes to migrate many features from your current site, from video and code embeds to social sharing widgets.
Your existing site may have other files, like PDF documents, downloadable files, or other assets. Moving those to their own asset server will make your site easier to manage, but you can also create folders in the static/ folder just like you would with images. If you re-create the same directory structure as the original site, your files will be accesible using the same URLs.
Checking Links
Images, hyperlinks, and other references might not entirely survive a migration, and spot-checking everything is time-consuming. The Broken Link Checker[63] command-line tool can help identify these issues quickly. It requires Node.js, but if you’re doing web work, you probably already have that.
Install the tool globally:
| | $ npm install broken-link-checker -g |
Then, run the hugo server command to launch your site.
After the site launches, run the blc command to recursively scan your Hugo site and let it show you what’s wrong:
| | $ blc http://localhost:1313 -r -o |
The -o switch tells blc to order the results so it’s easier to fix any issues. The -r switch tells the system to do a recursive scan.
Fix any broken links, and rescan your system until you don’t find new ones, as the previously broken links might lead to pages that have broken links of their own.
Once you have the content in a good state, you’ll want to replicate your theme.