NOTE: This article is now outdated. This site is now built with cccc. I'd recommend just reading it's source, but I may post a write up at some point.
So. I spent about 5 months trying to design this site. I'd try one layout, dislike it, try a new framework, try a new style, try new JS, a new look, new CSS, new content.
I wound up hating it all, although I still have backups sitting around Somewhere(tm). I really should have just gone with an existing static site generator, but they all seemed more complicated then I felt like learning. So I did the thing every reasonable geek does, I wrote my own. Well, sort of anyways.
We've got two main components. s5-generate.sh, and s5-render.
s5-generate literally does nothing except for create a directory and populate it with three almost empty template files: document-footer.html, document-header.html, and html-header.html.
When you start s5-render in a directory containing all three of these files, it will recurse down each subdirectory, rendering each markdown file it finds to index.html, while tagging on each of the template files in this order:
html-header.html: For your doctype and CSS declerations.
document-header.html: For whatever you want the header of your site to be.
*.md: For whatever your content is.
document-footer.html: For whatever you want your footer to be.
In addition, if s5-render happens to find a document-header.html inside of a directory it's traveling through, it will use that instead of the file at the top, so that it's simple to implement things like tabs for sections, without needing JS or PHP.
Now, I should make it clear that most of the heavy lifting is done by external programs, and there are some very bad assumptions made.
First of all, s5-render assumes there is a POSIX shell installed at /bin/sh. It won't work if there's not. I don't know what it will do. It may do nothing, or it may blow up your power supply. Who knows.
Second, s5-render uses said shell to orchestrate the opening/closing/reading/writing of files. If there is a maliciously named directory inside the paths that you run this on, nasty things could happen. I probably won't bother fixing this, because you should know what you're running it on, and it's simpler to build/maintain this way.
Third, it assumes that "cat" is going to function as normal. Presumably if you have a POSIX shell, this will be the case.
Third, s5-render will use whatever program is executed by running:
$ sh -c "markdown"
The program assumes that if this markdown is run as
$ markdown file.md
that it will output the html for that section (without adding tags
such as <body>) to stdout. If it doesn't, who knows
what will happen.
The biggest reason is that it is simple to construct. It just takes all of the tools I would have used by hand, and makes them automated in a nice easy way.
The other reason is that it makes it easy to implement my own functionality piece by piece, if I so desire. I considered using a crate to implement the markdown renderer inside of s5-render, however, I wanted this program to be both quick to write and easy to compile using only rustc/the Rust standard lib. This way, if I want to replace this functionality at some time, I just need to write a new markdown renderer and alias it to markdown, and it will seamlessly continue working with s5-render.
Same thing goes for cat, although I don't feel any real urges to reimplement this.