mmap.page

My Lume Setup

This site was hosted at GitHub Pages before. Thus, I have used Jekyll for many years. I have considered migrating to other static site generators several times.

But I'd like to keep the source of the content in the same way:

  1. I'd like to use mostly standard GFM, which renders nicely on GitHub and is compatible with a lot of programs.

    This rules out a lot of static site generators without writing a customized Markdown reader. For example, the default Markdown reader of Pelican uses <{filename}../article.md> for internal links, and its Pandoc plugin expects all Markdown files to start with a YAML header.

  2. I prefer a content first directory structure, not nesting Markdown files under a specific directory.

    This again rules out a lot of static site generators. For example, Hugo assumes a content directory.

  3. I do not want JavaScript at the client side.

As far as I know, the static site generators satisfying these needs are Jekyll, Eleventy, and Lume.

Eleventy, as a meta static site generator, allows customizing almost everything, while Lume is more out of the box.

Finally I migrated to Lume, allowing me to stop writing Liquid templates, which is my main pain point for Jekyll.

The migration process was easier than I thought, since Lume also supported Liquid templates. The only thing I find missing is using README.md as the index page. This nice feature of Jekyll makes browsering the Markdown files more convenient on GitHub. However, customizing destination URL is easy in Lume. I wrote a trivial url function in configuration to implement this feature.

However, I am not happy with Lume 3.0, which introduces a lot of breaking changes for subjectively better redesign. Particularly, it dropped the support for Liquid templates, which requires me to either maintain a Liquid plugin myself or migrate existing Liquid templates to something like JSX. However, I have motivation to do neither. So I let GitHub Copilot to rewrite the Liquid templates to Nunjucks which has a similar syntax to Liquid. It turns out GitHub Copilot is smart enough for this task. However, it seems GitHub Copilot is unfamiliar with Lume so it does not know YAML front matter is supported in templates for Lume and also it is necessary to use the safe filter to avoid escaping HTML tags, which liquid does not escape by default.