Migrate from Jekyll to Hugo

by: Joe Watkins

  • 16 April 2016

Early one Saturday morning I found myself unable to write a new blog post because my Jekyll site would not build. I was in what we call Dependency Hell!! This prompted me to research alternatives to Jekyll and this is how I found Hugo. In this post I’ll show you how convert a Jekyll site to Hugo.

Jekyll is an awesome static site generator and by no means do I mean to bag on it in this post. I just could not handle all of the dependancies that came with using it. If I updated Ruby something would break,.. if I updated my OS something would break.

I did finally fix all of the build errors in my Jekyll site but it took all weekend of nerding out to do it. I was bound and determined to find a better and more trustworthy solution for my blogging platform and Hugo was it! It is a binary that works across multiple operating systems and is a cinch to install. You’ll find yourself up and running in no time!

I’d like to start with a fresh install of a Jekyll site and migrate that to a Hugo site. You can build upon these basic steps for your Jekyll-based site. Hugo makes it fairly simple to move things over. GitHub Pages offers free hosting for static websites and works well with Hugo.

In this post I will assume you have a basic understanding of the command line, you have Git, Ruby, and Brew installed.

TLDR

Hugo offers a very easy-to-use Jekyll to Hugo importer.

$ hugo import jekyll path/to/jekyll/root path/to/hugo/root

Install a Jekyll site

Let’s install a basic Jekyll site and get it running.

1. Install

$ gem install jekyll
$ jekyll new my-awesome-site
$ cd my-awesome-site
$ jekyll serve

Jekyll site

If you are having issues getting thing installed try the troubleshooting page.

Install Hugo

Follow the instructions below to install Hugo using brew. You can learn more from the Hugo QuickStart Guide.

1. Install

$ brew install hugo
$ which hugo
> /usr/local/bin/hugo

2. Create Hugo site

Now you are ready to create your Hugo site. Let’s name ours bookshelf like Hugo’s tutorial suggests.

$ hugo new site bookshelf
$ cd bookshelf
$ hugo new post/good-to-great.md

3. Create a theme

Hugo doesn’t come with a default them so you need to create a themes directory and download a theme. Visit the Theme Showcase to see all the cool themes available:

$ mkdir themes && cd themes
$ git clone https://github.com/dim0627/hugo_theme_robust

4. Add content

Visit: /content/post/good-to-great.md and add some content below front matter.

First Hugo post

Start your Hugo site with the new theme:

$ hugo server --theme=hugo_theme_robust --buildDrafts

Hugo home page

Import content from Jekyll to Hugo

Hugo makes importing content from a Jekyll site very easy with the hugo import jekyll command. All you need to do is define the source and the destination paths and it will work its magic. It does its best at copying all your Jekyll posts and static content to your Hugo site.

$ hugo import jekyll path/to/jekyll/root path/to/hugo/root

Here is what it looked like for this demo on my machine.

$hugo import jekyll /Users/joewatkins/Desktop/my-awesome-site/ /Users/joewatkins/Desktop/bookshelf/

After running this command I got:

Importing…
Congratulations! 1 posts imported!

Jekyll post in file system

Below you can see the the Jekyll blog post is now in the Hugo site!

Jekyll post in Hugo Site

Handling Templates

Once you have your posts migrated you will want to start working on your theme. I elected to just start hacking up the Robust theme I started with. You can learn more about themes in the great documentation. Hugo recommends you override themes by adding new template partials to the /layouts folder.

You will want to copy over your static assets from your Jekyll site over to the /static folder in the Hugo site. When Hugo builds it will copy all the contents of that folder over to the /public folder which you would then deploy.

I prefer to stick my images, Sass, JavaScript, package.json, and Gulpfile etc. in the /static folder as well.

The templates out-of-the-box are fairly easy to understand. They leverage Go syntax and one can easily port Jekyll’s liquid syntax to Go. e.g. {{ my_page.title }} to {{ .Title }}

You will want to integrate the template structure from your Jekyll /_layouts and /_partials folders site to the Hugo theme /layouts folder or the theme’s /themes/theme-name/layouts.

Static Pages

Some Jekyll sites have static pages that are not posts. You may need to create these manually with $ hugo new page-name-here.md which will stick the static page in the /content folder. You can define the url of those pages in the front matter of that page.

Hosting your Hugo site on GitHub Pages

If you want to host your Hugo site on GitHub you will want to deploy the /public folder to your GitHub pages repo. Be sure to include a .nojekyll file in your /static before doing this. Learn more about the .nojekyll file.

Yay!

So far I have really enjoyed the speed and and how easy it is to use Hugo. Now when I have an idea for a post I don’t have to wonder if it will make it up to the web! Go get Hugo now!