Get the highlights in your inbox every week.
Hugo vs. Jekyll: Comparing the leading static website generators
Hugo vs. Jekyll: Comparing the leading static website generators
If you're building a new website, a static site generator may be the right platform for you.
Unless your spirit animal is Emily Dickinson, when you make a thing, you want to share it with the world. Sharing your work means that you need a website. Of course, you could simply partake in digital sharecropping and use any of the various social media sites to get your work in front of an audience. There sure are plenty to choose from... and not just "conventional" social media sites. With places like Artstation, Flickr, Soundcloud, and Wattpad, there's an outlet for you, whatever your medium.
And actually, you should use those sites. It's where the people are, after all. However, none of those places is truly yours. None is a home base that you control and that you can ensure will be there for people to find regardless of the waxing and waning trends of social media.
Control. That's the value of having your own place on the web.
But this article isn't about setting up a domain name and hosting for your website. It's for the step after that, the actual making of that site. The typical choice for a lot of people would be to use something like WordPress. It's a one-click install on most hosting providers, and there's a gigantic market of plugins and themes available to choose from, depending on the type of site you're trying to build. But not only is WordPress a bit overkill for most websites, it also gives you a dynamically generated site with a lot of moving parts. If you don't keep all of those pieces up to date, they can pose a significant security risk and your site could get hijacked.
Enter static site generators. You get the speed and security of static HTML pages, but with a workflow that's closer to the convenience of a dynamic site. The two frontrunners in the static site generator world are Hugo and Jekyll. (By the way, Paolo Bonzini has a great article on getting started with Jekyll.) But which one is the right choice for you? Hopefully by the end of this article, you'll have a better idea. We're evaluating both static site generators based on how quickly you can get started, availability of themes, editing workflow, and extensibility.
Fair warning, both of these tools will require you to work with them from the command line. Most of the commands are straightforward and easy to remember, but let's adjust our expectations accordingly. This is not a point-and-click interface.
Installation for both Jekyll and Hugo is pretty simple. Jekyll installs as a RubyGem, and Hugo offers a very handy all-in-one binary to get you started quickly. Because of the single install package, Hugo edges ahead here slightly. Although the RubyGems install method for Jekyll is easy in its own right, it does require that you already have a properly installed and configured Ruby environment on your computer. Outside of the community of designers and developers for the web, most folks don't already have that setup.
Once installed, though, both Hugo and Jekyll are pretty evenly matched. They both have great documentation and quick-start guides. You start a new site with a single command (in Jekyll, it's jekyll new <your_site> and in Hugo, hugo new site <your_site>). This sets up a general directory structure and scaffolding for your site. Directory structures and basic configuration are pretty similar. Jekyll uses a _config.yml file and Hugo uses config.toml (although you can use YAML or even JSON syntax with Hugo's config if you're more comfortable with either of those). The front matter metadata at the top of each content file uses the same syntax as the config. After that, all page content is written in Markdown.
I will say that in terms of getting you started with your very first statically generated site, Jekyll has a slight advantage over Hugo because it starts with some basic content and a default theme. You can use these as example templates as you start building your site. Hugo has no example content or even a default theme. That said, example content and default themes are usually the first things I delete when I'm making a new site with any tool, so Hugo actually saves me a step.
As I mentioned, Hugo doesn't ship with a default theme at all, so that's probably one of the first things you're going to want to set up. Jekyll has a decent default theme, though it's pretty bare bones. You'll probably want to go theme hunting with your Jekyll site, too.
Both Hugo and Jekyll have a pretty diverse assortment of themes for all manners of website types from single-page ID themes to full-blown multipage sites with blog posts and comments. Despite that, it's not exactly easy to find a theme that suits your needs. In either case, the place to go for themes—themes.gohugo.io for Hugo and jekyllthemes.org for Jekyll—is basically a single large page full of theme screenshots. Once you click on a theme, you can get some pretty detailed information about it, but that initial search is pretty rough. Hugo's theme page has some basic tagging built into it, but in general, theme searching and presentation is something I feel both projects really need to work on.
Theme management is also an interesting topic. In both cases, nearly every theme is a Git repository (often hosted on GitHub) that you clone into your website scaffolding. In Jekyll, there's an additional step of using RubyGems' bundle to ensure that the theme is managed with the site. Most themes already come with a Gemfile, making this step relatively painless. If the theme doesn't already have a Gemfile, it's fairly easy to add. In Hugo there's no bundling step. Just point to the theme from your config.toml, and you're good to go.
I've found that I'm partial to the way that Hugo handles themes. You clone (or create) themes into their own space in a themes subdirectory. Not only does it make it relatively easy to switch between themes when you're first starting out, but it also gives you the ability to override any component file of a theme with your own file. This means you can customize a theme to your tastes without messing too much with the source of the original theme, allowing it to stay generic enough for other people to use. Of course, if you have a change that you feel other users of the theme may find worthwhile, you can still edit that source and submit a pull request to the theme maintainer.
The workflows for building your site in Jekyll and Hugo are pretty similar once you have your initial configuration set up. Both have a live serve command that runs a small, lightweight web server on your computer so you can test your site locally without needing to upload it anywhere. The really nice thing is that whether you're running jekyll serve or hugo serve, both are configured by default to watch for any changes you make to your site as you work on it. When you look at the locally served version of your site in a browser, it automatically updates with any change you make, regardless of whether that change is to content, configuration, theme, or just an image. It's really quite handy and a great time-saver.
You write the content for your site in both systems using Markdown syntax. If you don't happen to be familiar with Markdown, it's a very simplified means of writing in plain text while still allowing for some nice formatting marks. It's very easy to work in and human-readable. And because it's in plain text, your content (and therefore your site) is easily version controlled. It's pretty much the main way I write almost everything these days.
New content can be added to your site scaffolding by manually creating files in the right place. It just needs to be a Markdown file with the appropriate "front matter" metadata at the top of the file. As with the configuration file, Jekyll uses YAML syntax for front matter, while Hugo will accept TOML, YAML, or JSON (default is TOML). That new page file needs to be placed in the correct directory within your site's scaffolding. In Jekyll, you have separate _drafts and _posts directories for storing your work in progress and your completed content pages, respectively. In Hugo, there's only a single content directory. You specify whether a post is a draft or not within that content file's front matter.
Now, although it's possible to do all of this manually, Hugo does offer some convenience functions to ensure that your new file is created in the correct spot in the scaffolding and that files are pre-populated with appropriate front matter. It's simply a matter of going to your site's directory in a terminal and typing hugo new content/<page.md> where <page.md> is the new page you want to create. You can even set up templates called archetypes that hold customized front matter for pages of different types (like if you have both a blog and a podcast on your website).
When your site is ready to ship, you can shut down your preview server and issue a command to build the actual pages of the site. In Jekyll, that would be jekyll build. In Hugo, it's just hugo. Jekyll puts the completed site in the _site subdirectory, while Hugo puts them in a subdirectory named public. In either case, once you do that, you have a completed static website that you can upload and have hosted nearly anywhere.
Both Hugo and Jekyll give you the ability to customize your site down to the smallest thing. However, in terms of extensibility, Jekyll currently leads in a big way because of its plugin API. Because of this plugin architecture, it's relatively easy to add functionality to your Jekyll-generated site with reasonably short snippets of code available through the Jekyll community or that you write yourself.
Hugo does not currently have a plugin API at all, so adding that kind of functionality is a bit tougher. There's hope that the ability to write and include plugins will be added in the future, but it doesn't appear that anyone is working on that yet.
By and large, Hugo and Jekyll are pretty similar. It really comes down to determining how you're most comfortable working and what your site needs. If you already have a RubyGems environment set up and you need the extensibility of plugins, then Jekyll is the way to go. However, if you value a simple workflow and a straightforward means of customizing your site, then Hugo would be your top pick.
I find that I'm more drawn to Hugo's approach, and in building a small handful of sites, I haven't yet had a need for any plugins. Of course, everyone's needs are a little bit different. Which static site generator would you choose for your site?