A thing I would like to do if I had unlimited time is to make an SSG with no frontmatter support. I think frontmatter was a mistake. Instead, you should just have two files with the same base name and different extensions, like post.json and post.md. Putting the frontmatter in the markdown just makes parsing it harder for no reason, since you need to support chained metadata filesystems anyway.
I prefer having the metadata in the same file to keep things mostly self-contained, and frontmatter is a simple solution that can be separated with a single regular expression.
What did you mean by “chained metadata filesystems”?
Most filetypes for creative works support this: reStructuredText, AsciiDoc, LaTeX, SVGs, all image types with EXIF, audio with ID3 tags, anything using Open Document or even Microsoft office formats, et cetera. What’s weird is that Markdown doesn’t yet folks use it for anything more than say a comment section formatter (& this doesn’t include the entire lack of features for technical writing ).
In Hugo, you can set arbitrary parameters like foo: bar, and they chain, so you can set it in your site config, override it conditionally in dev, override it again on the homepage, override that at the directory level, and then set it one last time in the frontmatter of the actual markdown file. It’s very useful.
The short of it is that frontmatter is a lot worse than it should be due to YAML’s overcomplication.
Ideally frontmatter should be a simple use of YAML’s multi-document streams. But no-one knows YAML supports multiple documents in a stream, so all static site generators (except mine) use ad-hoc delimiters between the YAML and the markdown. And they all (including mine) have an unnecessary extra parsing layer that re-does the work that ought to be done by YAML.
The second problem is that YAML indentation is underspecified. YAML uses | to introduce a multiline string, and you can use it to make a YAML document whose top level is a string (no enclosing array or hash), like
--- |
greetings
=========
hello, world
However, YAML implementations disagree about whether a top-level string needs to be indented. The original Perl implementations do not require indentation (as in the example above) but Python and Rust need indentation for strings (but not lists or hashes). So it ought to be possible to turn any plain text file into a YAML document by prefixing it with --- |\n but most YAML parsers get the indentation logic wrong. As a result, you have to choose between interoperable multi-document YAML without extra layers of parsing hacks, or Markdown without extra indentation.
My current blog uses YAML’s ... end-of-document marker to separate the frontmatter from the Markdown. This format is reasonably principled in design, and supported by Emacs and Pandoc as well as my SSG, but my SSG’s implementation is ad-hoc because the YAML parser I am using is not able to consume one document from a stream and return the rest of the stream to its caller.
Gah, this makes me cross enough that I’ve rewritten my blog rant in this comment. A friend of mine has cheerfully told me (over drinks, in response to earlier in-person versions of this rant) that it’s my own fault for choosing shitty technology, which is entirely true. YAML is overcomplicated and underspecified, and Markdown is oversimplified and underspecified.
Despite their crappiness, I’ve been using them for many years and am still happy with YAML frontmatter and Markdown for blogging. I only had do deal with the crappiness a couple of times but I have written dozens and dozens of articles. I’m not using YAML hard enough for its weaknesses to show, and Markdown has a built-in escape to HTML, so it works OK if you pay no attention to the hacks behind the curtain.
I avoided the Markdown part too & now I need less from my SSG other than as glue, aggregation using existing markup/metadata, & minor fixups instead of whole feature sets.
and Markdown is oversimplified and underspecified.
We did try to fix that! (Lobste.rs’ very own Markdown inputs use CommonMark.) Unfortunately the original underspecified nature of it means the spec isn’t easy on the eyes (and some people get (extremely (!)) grumpy about that), but the upshot is there is an actual Markdown spec you can learn, that works in many places, and is predictable.
In my SSG, I don’t use frontmatter indeed, and have the files content be just normal markdown. And I keep my metadata (date and tags) in the filename, as:
which, when rendered, is then stripped down just to the title-slug part, whereas <DATE_ISO> and <@TAGS> are extracted, for a timestamp and a tags list respectively:
Is the HTML-manipulating code readable? Nope, sorry. I wish it was. But at least it is relatively small, and the inputs are understandable to me, while in most SSGs I found, the DSL and conventions were always confusing and convoluted to me.
A typical post will have metadata like a subtitle or description, a share image path, multiple tags, series, layout type, etc. Putting it all into the filename would be very error prone since you generally don’t use a text editor for filenames and this will easily overflow the default width of filenames in a Finder window.
The SSG I used to use supported that (nanoc. It was a slight inconvenience to have to create two files for every post and to have to switch files to edit the title, etc.
Wow, what timing. I’m doing a (non-tech) programme at university, and we were encouraged to set up a portfolio-esque website, and they showed some freemium tools for that, which weren’t so appealing to me, and I made a note to check for Zig-based SSGs.
This is much more ambitious than anything I thought I’d find.
One option to consider is not using an SSG, and instead using the underlying markdown parsing & template rendering libraries directly. I’ve personally found that, if you need to maintain many similar website, SSG is a win. However, for maintaining a single website, re-using the libraries and writing the “main” yourself could be easier.
I am not saying that DIY is better for everyone, but rather I want to dispel a misconception that you need an SSG for a website (I certainly fell for it in the past).
Wow, great job. I really like how you dropped inline HTML and regular templates and instead have the markdown directives. I really like how the sections turned out too, this kind of thing keeps making me want to rip my hair out whenever I do something with SSGs.
SuperHTML templates are valid HTML and the templating logic is expressed through scripted attributes.
Interesting. The templating system reminds me a bit of TAL/METAL. One difference is that TAL templates can potentially be prefilled with example content - so they are trivial to style - they’re just html where attributes will be swapped out when rendering.
Interesting, thanks for sharing! In my case I guess the assumption is that you will develop your templates with the development liveserver running and watch the preview in your browser with the “live” data from a post.
That said being able to have placeholder data in a template has its own set of advantages.
Yes, these days live reload is common - and one problem with having a single template act as a working, real, html page is that it tends to conflict with basic DRY - you almost always want a shared header, footer and navigation.
But there was a certain elegance to a designer handing over html and css - and being able to simply use that as a template - filling in slots and keeping the sample content - even mostly allowing someone working only in html/css the ability to adjust the template later (breaks down in certain cases where complex loops/slots needs rewriting).
On a similar theme, I thought these were interesting:
A thing I would like to do if I had unlimited time is to make an SSG with no frontmatter support. I think frontmatter was a mistake. Instead, you should just have two files with the same base name and different extensions, like post.json and post.md. Putting the frontmatter in the markdown just makes parsing it harder for no reason, since you need to support chained metadata filesystems anyway.
I prefer having the metadata in the same file to keep things mostly self-contained, and frontmatter is a simple solution that can be separated with a single regular expression.
What did you mean by “chained metadata filesystems”?
Most filetypes for creative works support this: reStructuredText, AsciiDoc, LaTeX, SVGs, all image types with EXIF, audio with ID3 tags, anything using Open Document or even Microsoft office formats, et cetera. What’s weird is that Markdown doesn’t yet folks use it for anything more than say a comment section formatter (& this doesn’t include the entire lack of features for technical writing ).
In Hugo, you can set arbitrary parameters like foo: bar, and they chain, so you can set it in your site config, override it conditionally in dev, override it again on the homepage, override that at the directory level, and then set it one last time in the frontmatter of the actual markdown file. It’s very useful.
Oh, I have a rant about blog frontmatter
The short of it is that frontmatter is a lot worse than it should be due to YAML’s overcomplication.
Ideally frontmatter should be a simple use of YAML’s multi-document streams. But no-one knows YAML supports multiple documents in a stream, so all static site generators (except mine) use ad-hoc delimiters between the YAML and the markdown. And they all (including mine) have an unnecessary extra parsing layer that re-does the work that ought to be done by YAML.
The second problem is that YAML indentation is underspecified. YAML uses | to introduce a multiline string, and you can use it to make a YAML document whose top level is a string (no enclosing array or hash), like
However, YAML implementations disagree about whether a top-level string needs to be indented. The original Perl implementations do not require indentation (as in the example above) but Python and Rust need indentation for strings (but not lists or hashes). So it ought to be possible to turn any plain text file into a YAML document by prefixing it with
--- |\nbut most YAML parsers get the indentation logic wrong. As a result, you have to choose between interoperable multi-document YAML without extra layers of parsing hacks, or Markdown without extra indentation.My current blog uses YAML’s
...end-of-document marker to separate the frontmatter from the Markdown. This format is reasonably principled in design, and supported by Emacs and Pandoc as well as my SSG, but my SSG’s implementation is ad-hoc because the YAML parser I am using is not able to consume one document from a stream and return the rest of the stream to its caller.Gah, this makes me cross enough that I’ve rewritten my blog rant in this comment. A friend of mine has cheerfully told me (over drinks, in response to earlier in-person versions of this rant) that it’s my own fault for choosing shitty technology, which is entirely true. YAML is overcomplicated and underspecified, and Markdown is oversimplified and underspecified.
Despite their crappiness, I’ve been using them for many years and am still happy with YAML frontmatter and Markdown for blogging. I only had do deal with the crappiness a couple of times but I have written dozens and dozens of articles. I’m not using YAML hard enough for its weaknesses to show, and Markdown has a built-in escape to HTML, so it works OK if you pay no attention to the hacks behind the curtain.
I just avoided YAML altogether.
I avoided the Markdown part too & now I need less from my SSG other than as glue, aggregation using existing markup/metadata, & minor fixups instead of whole feature sets.
We did try to fix that! (Lobste.rs’ very own Markdown inputs use CommonMark.) Unfortunately the original underspecified nature of it means the spec isn’t easy on the eyes (and some people get (extremely (!)) grumpy about that), but the upshot is there is an actual Markdown spec you can learn, that works in many places, and is predictable.
Hm interesting
My solution:
So it’s
Github understands it, but I don’t use YAML anywhere
I only need one level of key-value pair
e.g. see the little boxes at the top - https://github.com/oils-for-unix/oils/blob/master/doc/hay.md
In my SSG, I don’t use frontmatter indeed, and have the files content be just normal markdown. And I keep my metadata (date and tags) in the filename, as:
<DATE_ISO>-title-slug.<@TAGS>.mde.g.:
20240611-1826-forge-horizons.@review.@ironsworn.@bud.mdwhich, when rendered, is then stripped down just to the
title-slugpart, whereas<DATE_ISO>and<@TAGS>are extracted, for a timestamp and a tags list respectively:https://akavel.com/forge-horizons
Also, I stole the core idea of the rest of the SSG from the Soupault SSG: I don’t use an (increasingly complex) templating language; instead, I render the Markdown to HTML, then use Lua+Rust to further operate on HTML, mashing together pure HTML page templates with the rendered HTML of the Markdown contents. Because Lua is Greenspun’s Tenth Rule embraced and accepted.
Is the HTML-manipulating code readable? Nope, sorry. I wish it was. But at least it is relatively small, and the inputs are understandable to me, while in most SSGs I found, the DSL and conventions were always confusing and convoluted to me.
I have Hugo set up to use the filename as the pub date and slug, but I’m not sure I would want to use it as the other metadata, like tags and whatnot.
Honestly curious why? 🤔 though you totally have a right to do as you prefer regardless of whatever.
A typical post will have metadata like a subtitle or description, a share image path, multiple tags, series, layout type, etc. Putting it all into the filename would be very error prone since you generally don’t use a text editor for filenames and this will easily overflow the default width of filenames in a Finder window.
The SSG I used to use supported that (nanoc. It was a slight inconvenience to have to create two files for every post and to have to switch files to edit the title, etc.
Examples: https://github.com/wezm/wezm.net/tree/master/v1/content/technical/2019/03
Parsing isn’t very difficult, you split on the separator and parse the parts separately: here’s how I do it in a different project: https://github.com/wezm/pkb/blob/7646745dc8c64a1f178211f48ca15fdce909e77c/src/page.rs#L181
The parsing isn’t hard, but my text editor doesn’t know how to do it.
Small typo here:
(Ciao, al prossimo SYCL a Milano!)
Fixed, thanks! (👋)
[Comment removed by author]
I quoted the second bullet point because it’s spelled “humans” there! :)
:facepalm: sorry! didn’t even see it. :)
Wow, what timing. I’m doing a (non-tech) programme at university, and we were encouraged to set up a portfolio-esque website, and they showed some freemium tools for that, which weren’t so appealing to me, and I made a note to check for Zig-based SSGs.
This is much more ambitious than anything I thought I’d find.
One option to consider is not using an SSG, and instead using the underlying markdown parsing & template rendering libraries directly. I’ve personally found that, if you need to maintain many similar website, SSG is a win. However, for maintaining a single website, re-using the libraries and writing the “main” yourself could be easier.
I am not saying that DIY is better for everyone, but rather I want to dispel a misconception that you need an SSG for a website (I certainly fell for it in the past).
And if your sites are mostly text with boring formatting, as mine happen to be, you can just write HTML.
That is writing an SSG? What you’re describing sounds to me like writing a very small one off task specific SSG.
Which I think is a fine idea. A single task SSG like that is just handful of for loops with some sprintfs and html escaping in there.
Wow, great job. I really like how you dropped inline HTML and regular templates and instead have the markdown directives. I really like how the sections turned out too, this kind of thing keeps making me want to rip my hair out whenever I do something with SSGs.
Interesting. The templating system reminds me a bit of TAL/METAL. One difference is that TAL templates can potentially be prefilled with example content - so they are trivial to style - they’re just html where attributes will be swapped out when rendering.
https://pagetemplates.readthedocs.io/en/latest/
Interesting, thanks for sharing! In my case I guess the assumption is that you will develop your templates with the development liveserver running and watch the preview in your browser with the “live” data from a post.
That said being able to have placeholder data in a template has its own set of advantages.
Yes, these days live reload is common - and one problem with having a single template act as a working, real, html page is that it tends to conflict with basic DRY - you almost always want a shared header, footer and navigation.
But there was a certain elegance to a designer handing over html and css - and being able to simply use that as a template - filling in slots and keeping the sample content - even mostly allowing someone working only in html/css the ability to adjust the template later (breaks down in certain cases where complex loops/slots needs rewriting).
Isn’t there already a SSG called Zine? Any relation to this Zine written in Rust?
There’s probably a thousand different things called Zine. No relation with any other similarly named project.