ebullient·works

SSG with Obsidian and Lume

All tech has a cycle, including what we use to make our websites. I come back to this place every few years[1], and it is always a ramble when I do.

I am setting up a new website for someone else, which has given me the lovely excuse to revisit this perennial topic. While not a developer, they are familiar with Obsidian (and its markdown extensions). Messing around with Obsidian and themes has also lead to some familiarity with CSS, which is a bonus.

I have a few objectives for the exercise this time around: I want site content (blog posts, section pages) to be previewable and editable in Obsidian. For simplicity, I will start by publishing the whole vault (no filters other than the ubiquitous draft frontmatter flag). I am thinking most "pre-process" stuff (markdown file/link construction) can just be done with the Templater plugin.

From CMS to SSG

When I first started my own blog back in the stone ages, we all used a database-backed Content Management System (CMS). In hindsight, this was wild! We didn't have containers, we didn't have easy-to-use virtual machines, we didn't have easy-to-use cloud hosting. We had to install and configure a web server, a database server, and a scripting language (PHP, Perl, Python, Ruby, etc). We had to configure the CMS, and then we had to write our content in a web form. We had to worry about security updates and database backups. And we did this for fun!

Static site generators (SSG) keep your content in flat files. No database, no web form. You write your content in a text editor, and then you run a command to generate your website. You upload those generated files to a web server. With the advent of GitHub and GitHub Pages, this has a lot of appeal, as the whole thing can be automated: your blog post is committed to a source code repository, and continuous integration (CI) pipelines (like GitHub Actions or Netlify) can generate and deploy your website. Easy peasy.

Current Tool - Hugo

My current blog tool of choice is Hugo. It uses markdown (or asciidoc) files to generate a website. It is fast. It is mostly easy to use, but there are some sticky spots here where you need to go remember what a shortcode is and how it works.

Hugo is written in Go, and you work with it as a single binary command, which is orders of magnitude easier to deal with than Jekyll [2].

Unrelated to web/blog things, I have been using (and abusing) Obsidian for the past few years. It is plastic and fluid and it evolves with my brain; it is also changing how I create and work with notes. I am starting to find that I want to work with my blog in the same way I work with my notes. I'm not sure I would merge my blog into my Obsidian Vault, but if I have more control over how content works and is rendered, it's a possibility.

Obsidian and Hugo

There are some great resources for getting Obsidian to work with Hugo. It is definitely a fan favorite. Obsidian + Hugo = ❤️‍🔥 is a great starting place.

The virtual file overlay provided by Hugo module mounts allows you to keep all of the Hugo files outside of the vault. Other improvements, like markdown render hooks[3], make it easier to work with plain markdown. That said, I've run into some edge cases where I've had to do some weird things to get the output I want. URL behavior is also starting to irritate me.

Looking at Lume

Given some Hugo gotchas and my own frustration at my limited ability to tweak behavior, I am looking at Lume, another static site generator. It is in a corner of the ecosystem I hadn't noticed before (it uses Deno).

Configuration has been straight-forward, and while I haven't tried to adapt some of my more byzantine site constructions yet, I've already found it easier to customize behavior.

Obsidian and Lume

Lume uses markdown-it for markdown parsing. There are a few plugins that already claim to add Obsidian capabilities that I haven't evaluated in full.

What I could not find was a plugin that would support Obsidian-style admonitions and callouts.

I did find some promising options:

I created ebullient/markdown-it-obsidian-callouts to handle both Obsidian callouts and code-block admonitions care of the Admonition plugin. It uses Obsidian default icons and callout flavors.

Next

  1. Movable Type (2002?) -> Textpattern (2005) -> NucleusCMS (2007) -> Jekyll (2017) -> Hugo (2020), and now Lume. ↩︎

  2. The ruby ecosystem is a nightmare, I avoid it whenever possible. ↩︎

  3. Markdown Render Hooks alter the behavior of markdown rendering. These hooks make it possible to use standard markdown syntax for content links, but there are caveats for finding the right link target that make this a less trivial exercise than it may seem on the surface. ↩︎