From Publii to Hugo

my new blogging workflow

Tuesday, March 24, 2020

Why leave Publii

Yes, I again switched my blogging workflow. Although Publii was easy to use, created a good looking, fast and responsive site it still missed some features. Where it falls short:

  • Machine independant workflow, I placed my Publii folder in Dropbox to have it synchronised across machines but generating the site from a Dropbox folder pushed my CPU’s well over 100%
  • Creating posts with code blocks, writing a post in Publii and adding a piece of code is cumbersome and error prone.
  • I use Markdown for notes, for presentations and I want it for my blog. So far Publii does not support it.

I’m not saying Publii is a bad choice for a static blog but it just does not fit my needs. I have recommended it in the past to colleagues and friends who wanted to re-start their website or blog and I will continue to do so.

Machine independant workflow

For a machine/device independant workflow I see the following requirements:

  • Content is accessible from everywhere
  • Site generation should be automated
  • Site deployment should be automated

With these requirements a Git-based solution is a logical choice. The site generation and deployment can be handled by GitHub Actions or GitLab CI. GitLab offered a Hugo based workflow that was an important reason to go for GitLab.

For site-deployment my hoster only provides sFTP access. Not the most convenient but I with the help of LFTP it was possible. How that was done is described in a previous post

With the git-based workflow it is now possible to get the source from GitLab, add or modify content, commit the changes and let Gitlab take care of the rest. Even from an iPad!


Hugo is fast, posts written in Markdown, a lot of nice themes to choose from and since it’s Markdown adding code-snippets is a breeze.

Is it perfect, no. Some parts (Pages Resources or Leaf and Branch bundles) are still really complex but most of the time I can work around it 😉.

What theme

As a base theme I chose the “Clean White” theme. It has some regional specific features, a nice clean layout and is still very customizable.

I added it as a git submodule and did some modifications.

Automating and building the search-index

The “Clean White” theme uses Algolia to power the search. Detailed instructions on how to build the search index with an on-premise setup are included in the documentation but that does not fit the fully automated idea I had. Therefore I implemented it in the GitLab/CI workflow

Theme modifications

The theme enables you to overide parts of the site. So no need to modify the sources just add layout files in your own repo to sculpt the site.

My modifications:

  • Header images can be added to the ‘img’ directory of a page-bundle. With the name “header_image” and a .jpg or .png extension it is automagicaly added as header image.
  • The TOC is by default displayed at the top of the page, I moved it to the right side of the page.
  • Added a logo to the top-left corner instead of the site-name.

What is on the wishlist

  • Modify content from other sources and add them here
  • Copy buttons in the code blocks
  • Reduce the height of the header_image
  • Workflow to resize and reduce size of images
  • Templates to improve the workflow
  • Image resizing but then from Markdown
  • Setup my workflow to write posts on my iPad

Lessons learned

The fact that my hoster still uses sFTP is annoying and something to consider changing in he future but when I look at my wishlist, what is already done, how much effort it took and the result. There was a learning curve but for now I’m satisfied the result.