Stag - first insights

  • stag, blog, hugo
  • 7
  • 1
  • finished

I’ve been silent for a while. First, I’ve been on a vacation during which I switched off and it was great. Next, all of Brandon Sanderson’s books really take a while to read and after years of living otherwise, I’m back at the point where I prefer spending evenings with a book in my hand than with a laptop. Then I have started the big project of decluttering my house and selling a lot of things which were just laying around unused, gathering the dust. Taking photos, answering questions, packing and sending these things really takes some time!

So basically: life happened. But miraculously I found some time for a new side project: a static site generator named Stag.

Building one was one of the things that I had in the back of my head for a while. Surprisingly, it turned out it’s quite simple. However, me being me decided that it must be super-extensible. Not only that, but it must be super-easily-extensible. Why? Because I’m tired with having the braindead regular expression to simply add a drop-cap for each post in Hugo. And awful templates syntax. And syntax for page-specific files (they’re called “resources” I think). And probably a million of other small things which I feel are overcomplicated for my simple needs.

It required some thoughtful architecture but after some code wresting I figured out that I’ll go Pelican’s path and base the whole thing on signals and slots. Which is probably meh, but it works quite well.

One problem with signals is that their listeners are called in undefined order1. Solution to that isn’t pretty: add enough signals that everyone can fit themself and define what’s available to the plugins at different stages of site generation. For example, when Stag calls site_initialized signal, all listeners should assume that no pages are read yet. Or when file readers finish their job, listeners shouldn’t assume that there is any output generated from these files (meaning, no format conversion, e.g. Markdown to HTML, happened yet).

At this point Stag is probably able to generate my whole site without changing even a single line in its code. What’s missing are some unimplemented macros (shortcodes in Hugo’s terminology). I also want to move some of the most common macros and templates (which are now specific to my blog) to Stag itself2. I’m also missing some goodies like support for drop caps, hidedate parameter (which hides the date on a particular page) etc. Maybe I’ll find some time this week to address these things and deploy the new blog.

Word of warning though: RSS URL will change, but hopefully redirect I’m going to set up will work. I won’t set it on server level though, but it will be HTML/XML redirect, so I guess it totally depends on the client how it’s going to be handled.


  1. Not entirely true. The order is defined, but fragile enough that it’s better to think about it as undefined. 

  2. For example template for RSS or macros for cross-site references.