Possible migration from Jekyll to Hugo

[fsimonis]

Whilst looking for alternatives to Jekyll I noticed that Hugo has many features that makes it very suitable for a replacement in our case.

Documentation under https://gohugo.io/documentation/

I gather Pro, contra, and unclear points underneath:

Pro

Installation

Jekyll and its plugins are based on ruby.

Hugo is a linked executable which can be downloaded and installed directly from their repo.

Subprojects

Subprojects/including other repositories are not supported by Jekyll.
The current workaround is a custom plugin that imports data from submodules.

Hugo supports additional content directories to cover submodules and even allows exporting data from external repositories at build-time using hugo module.

We currently use docs folders in our repositories, so we would need to mount them into the content directory.

I am not sure if this requires changes in the imported repositories though.

Menus

Currently handled using sitebar data and custom logic and templating.

Hugo has build-in support for menus.
Sites can define where they are located and menus can be rendered differently in various places.
We only would have to customize the rendering template.

Git info

Currently handled using an unmaintained plugin which provides the last-modified date.

Hugo has built-in support for git info including last commit of a page, author and also all authors of a page.

SASS

Currently handled by the jekyll-sass-converter which is a direct dependency of jekyll and suffers from the problem in #471

Hugo directly uses dart-sass, which is essentially what the newer google-protobuf version of the converter does.

Algolia

Currently handled by the abandoned jekyll-algolia gem, which has a flaky dependency and produces overly long records.

The Hugo website itself uses Algolia though, so there is a way to index hugo projects in some way.

Paper citations

Currently extracted from Google Scholar which often fails due to rate limiting.

Hugo supports external data source, meaning we can keep this information updated somewhere else and import it when needed.

Image handling

Currently there is no asset pipeline. Image will be included in the website as is.

Hugo has an asset pipeline that can resize images to improve the experience on mobile.

Basic SCHEMA metadata

We currently generate some schema metadata using jekyll templates.
Hugo renders some basic schema metadata by default.

Contra

Template engine

Jekyll uses the Liquid template engine.

Hugo uses Go templating, which requires porting.

Extensibility

Jekyll is fully modifiable using ruby plugins.

Hugo does not support plugins.

Flat output

The output of Hugo is scoped and extensionless by default. We either need to use the permalinks for every page or use redirects from the existing permalinks using aliases.

Redirecting

In jekyll, the plugin jekyll-redirect-from provides internal redirects and redirects to external pages.

Hugo implements internal redirects with content aliases, while redirects to external pages are not yet supported.
We need to manually implement redirection via metadata (which the jekyll plugin generates).

Unclear

PDF generation

I am not sure if hugo can selectively hide pages to generate a special version of the website for the PDF generation.
It looks like this could be done with segments though.

[uekerman]

Thanks for the research and summary. What would be your best guess, how much working hours would this take if somebody experience like you would pick this up?

[fsimonis]

I tinkered a bit with their quickstart and tried a quick and dirty port of the website. This is what I learned:

Regarding the content

• Using flat urls feels a bit weird with hugo, it's hierarchical without extensions by default.
• The content files need some restructuring and renaming to fit the sections philosophy.
• A lot of logic and info from the frontmatter of the files moves into templates, which is great.
• Current permalinks needs to be used as aliases.
• Each section should now have some kind of overview page.
• Using images looks straight forward.
• I haven't tried including external repos yet. But there most likely needs to be some kind of content rewrite to add an _index.md and gather all files in a single directory, which should make mounting easier.
• No idea regarding the Google Scholar citations.

Regarding the layout template

• Apart from the port to go template language, a big part of the logic inside the template needs to be rewritten
• Problems feel significantly easier to debug than in Jekyll liquid. Error messages are more helpful.
• An alternative would of course to move to a different theme entirely. The theme of the Hugo website itself could be a good base.

Regarding Hugo itself:

• It seems to enforce better organisation of the content.
• Updates are near instant, which makes it way easier to track down a problem and makes life editing less sluggish.

What would be your best guess, how much working hours would this take if somebody experience like you would pick this up?

The content restructuring seems relatively straight forward, maybe 2 days.
The layout porting is what I think will absorb more time, maybe 3 days.

So vague optimistic guesstimate of 1 week, or 2-3 weeks with the usual software estimate modifier.