Migrating From Jekyll to Hugo, deploying with Github Pages

My current blog expose posts with the following path

The default configuration exposed these links as

After some search I found these can tweaked with the permalink setting, I don’t know exactly why but this was only taken in account after the [params] section.

Which made the post accessible to this url.

At some point I might be considering the use of Hugo aliases and change the urls of the post to something like

…

Actually I got this wrong, Jekyll’s permalink configuration /:year/:month/:day/:title has a small unusual thing, when reading the doc :

So when setting /:year/:month/:day/:title/ in Hugo config.toml the permalink are not exactly what I hoped them to be, this actually the title from the front matter of the article. I had to resort to the technic used in this blog Convert Jekyll to Hugo Permalinks to keep the same permalinks.

gsed is gnu-sed from brew install gnu-sed on MacOs. Because newlines don’t work with the BSD sed .

My Jekyll site had some other pages, those where located in the _pages of my Jekyll site. In order to understand how the site works, I needed to read content organization documentation. The only thing I had to do is copy these files over the content directory of the Hugo site.

It’s even possible to do a layout like that.

I preferred the easy way in regard of these page content. Also, I wanted my post in the posts folder instead of post, I just had to rename the folder and that was it.

Finally, in order to access the content I needed to add the menu entries, like that. I didn’t need to read the menu documentation for it to work, but there’s more stuff possible when going over it.

This will be appreciated for languages that have diacritical marks like French. So defining the permalink with /:year/:month/:day/:title/ lead to use the post title for the link, however some have accent that are then url-encoded :

I didn’t find it in the Hugo doc, but in the Hugo issue tracker, it’s possible to add in the config.toml, this setting is not part of any section.

Will then make the urls as follows :

The Hugo import command copied over a few Jekyll stuffs that are not anymore useful. So git gives me these files for example that could be removed. I included the favicon as well, as I wanted some refresh.

However, the CNAME file has been moved to static folder, which is wrong, let’s put it back at the root of the git repository.

Remove unused Hugo themes

Adapt my .gitignore

I found this issue #18 on Hyde-hyde theme, however this issue referred to an old version of the theme which has since been updated.

One thing that is interesting and useful is how Hugo allows overriding parts of a theme. The themes are located in the ./theme folder, e.g.

In order to override parts of the theme it’s possible to copy the file in the root of the Hugo site (following the same directory structure). For post lists, I identified two files in the theme directory :

These files need to be copied over the root of the Hugo site with the same relative path. And modify them as needed.

Here I’m using the Hugo internal template for pagination but one can image using a custom template. The .Paginate directive was taken from pagination doc, however the doc have a slight issue, the where query needs to be where .Pages “Type” “in” “posts” keyword.

However, I noted that other lists do not render anymore, for example /tags or /series, this is because the file we modified affect all list based page, search where the page-list/content.html partial is used raises the general list.html located there themes/hyde-hyde/layouts/_default/list.html. Since I want the pagination only for posts at this time, I just have to create a structure like this in my root Hugo site.

I created a posts folder in the layouts directory and in the layouts/partials, then I moved the file layouts/partials/page-list/content.html to layouts/partials/posts/content.html and merged the content of layouts/partials/posts-list.html replacing the Hugo function {{ partial "posts-list.html" . }}, and I removed this file as it breaks other taxinomies. Finally, I had to create the layouts/posts/list.html file, that invokes {{ partial "posts/content.html" . }}.

Here I needed to modify the index layout to only display the last X recent post.

This trick is not current as you need to wrap the query part with the first function (first .Site.Params.landingLastPosts <query>), and I added landingLastPosts in the params section.

EDIT: the comment system has been migrated from Disqus to Giscus.

So Hugo supports Disqus comments, but the thing is that site is generated by a theme and the theme may or may not handle comments as you wished, so it’s necessary to look at how it’s done in Hugo and in the theme depending on the requirements.

For my Jekyll site, my comments had to be migrated from a Wordpress engine, posts on Wordpress have different Disqus identifier that is now specified in the front matter, and this identifier was passed to Disqus script configuration. Here’s my Jekyll website relevant part:

This script was crafted manually to pass identifier coming from the old days when it was powered by Wordpress. Looking at the Hugo template for Disqus, I know there are other elements of the page configuration that are actually passed over to Disqus.

So that’s interesting but life isn’t that simple as theme may override as well internal template by their own; the theme I chose uses a template that doesn’t use the Hugo internal to initialise Disqus script, my them file is located at layouts/partials/page-single/comment/disqus.html. THa leaves me no choice but to to override this partial comment template of the theme layouts/partials/page-single/post-comment.html, it this I merged the Hugo internal template, and I tweaked the template of the script initialization to behave the same as my old Jekyll site. The most important bit is here :

Also for reasons that I don’t understand, the .RelPermalink / .Permalink Hugo functions escape the URL’s slashes with backslashes when the template function is placed inside a single quotes of the JS script. The only workaround was to use printf "'%s%s'" then pipe to safeJS function.

Then just in case the admin is available here https://<you disqus short code>.disqus.com/admin/settings/general/.

Now permalinks for posts are defined as /:year/:month/:day/:slug/, the slug is a special entry that is computed by Hugo or set in the front matter of the content page. And the permalinks are used as Disqus identifiers. In order to have stable permalinks and Disqus identifiers if changing the generation backend, it’s better to write it down.

I name my posts with a date then a string that is likely the title of the post, e.g. 2020-04-01-manage_dotfiles_with_chezmoi.md. With the permalink structure in mind I need my slug as the part of the filename after the date.

So let’s use the Hugo archetypes that will allow us to create a new post. It can be simply done by creating a file archetypes/posts.md with a content like:

The slug then becomes the part of the file without the date. Note that this archetype file can be easily duplicated as an Asciidoc file by adding a posts.adoc.

However, for now it’s necessary to write manually at the beginning of the filename the ISO-8601 date, meaning we have to write :

So that’s what I had hoped. Yet I got this message in the repository settings.

I tried to create an empty gh-pages branch. Here’s some useful git command by the way:

But the settings page still insists that it should be done on master, not quite the same as mentioned in the GitHub Pages doc. I decided to drop this approach and removed the gh-pages branch for now.

Finally, by trying things out, if there’s an index.html file on master, then the branch files will be used to serve as static content. Following this clue, removing all files in master but CNAME, it is enough to publish Hugo generated file from the ./public folder to the master branch.

Due to this Github Pages constraint the Hugo directory structure and site files are in another branch like hugo-sources that is configured as the default branch of this repository.

For that let’s use Github Actions, it’s possible to declare what needs to be done in a yaml file, and it appears the market place has everything I need to do that

Let’s configure the same version as the local one

Version 0.69.0, and it is important to activate the extended flag as well.

The only thing that we need is a deployment key as documented here.

Going there, and add the public deployment key, check Allow write access :

Then add the secret key here named ACTIONS_DEPLOY_KEY.

Don’t commit these files. But it may be useful to store them securely.

At the time I performed this migration

This was a requirement for user and organization page sites (<username>/<username>.github.io) to set the master branch as the publishing branch as mentioned in the actions-gh-pages@v2 Repository type - User and Organization section. Meaning I kept the Hugo sources in another branch i.e. hugo-sources and configured accordingly le the publication branch.

This gives us the following configuration in .github/workflows/<name of the workflow>.yml :

After this file has been pushed, it’s possible to inspect what this action has been doing, for how long, etc, at the repository actions page