I’ve been using Jekyll for a few years now. Main reason to use it, is its nice integration with Github Pages. However the frustrations now have outweighted the advantages.

Not so cool

What annoyed me tremendously is getting Jekyll to run. All the ruby issues were hard to solve for me.

Next in line is how to structure the content. As long as you only want to blog, Jekyll is good enough. If you need another kind of collection, then things get tedious. I took me a very long time to figure out how to get my talks organized and displayed just the way I want.

Finally getting the layouts right is not that easy. It takes quite some tampering to make it right.

Hugo as alternative

I’ve already read a lot about a Hugo. It seemed interesting, but never took the time to look more into it. Now the time has come, and so far all is good.

I really like the exhaustive docs, and the very nice quickstart. Next is the built-in import from jekyll. And finally, no tampering to set up a collection of similar post (eg blogpost, talks, recipe, quote, …). The structure is completely file-based.

Also browser hot reloading after a rebuild - Awesome!

Getting my hands dirty

I basically followed the quickstart instructions.

  1. Install hugo using brew

  2. Create the new site

  3. Add a theme - I chose the hermit theme as it’s complete and fits my needs

  4. Import the jekyll post using the hugo import jekyll command. The blog posts were wrongly copied in the post folder instead of the posts folder.

  5. The import command didn’t import all content: my talks and pages weren’t copied. I had to manually create the talks folder and the folders for the static pages such as the about page.

  6. On some pages I used css(colors for presentation post) and javascript(linkedin badge on the about page). This wasn’t rendered as both css and js in markdown is considered as a security issue. This was fixed by setting the unsafe propety of [markup.goldmark.renderer] to true.

  7. Next I wanted the same overview of my talks in descending order. I took some time to figure out, but it was easier than to get the same overview in Jekyll.

    In short, a theme provides a layouts. An overview of posts, talks, … is rendered using the list layout usually located at themes/<themename>/layouts/_default. You can override this by creating a layout folder next to your content folder. In my case a I create a subfolder talks (the content I want a custom overview for) and put my custom list template in there. The full path to the custom list template is /layouts/talks/list.html.

  8. Next I had to fix the internal links. That’s an easy find and replace for post_url - the Jekyll syntax to link to other content- with Hugo’s specific link syntax.

  9. On the talks pages there was a table of content in the sidebar. The Jekyll {{toc}} command is off course no longer rendered.

  10. Finally I had to check all static assets. Seems that they were properly imported with the hugo import jekyll command.

Only thing left to do, is how to get the generated files on github pages. To be continued.