A brand new toaster

This week I released a new version of Toaster, my website generating program, and wrote a better user manual for it.

Toaster

Toaster has existed for a while now in various forms. I originally wrote Toaster back when my website was hosted at breadpunk.club/~toast, so that I could write my website as a folder of markdown files and have Toaster generate some HTML with a nice site navigation toolbar. I’ve never enjoyed writing HTML by hand, it’s such a mess.

Here’s a screenshot from that original website for a lark:

It’s cliché for programmers to talk about building a static site generator, but, you know, surely mine is different. There are a bunch of these kinds of programs that already exist, but I had a few specific requirements that needed to be met:

• Needs to be simple, running as a single standalone executable (this already decimates the list).
• Needs to be fast, generating a big website in under half a second.
• Needs to be flexible so that I can throw in recipe rendering and redirects and whatever else.
• Needs to check every link on the website to make sure I haven’t broken something.
• Needs to make every link relative to the current file so that the website can be browsed offline. I don’t always have internet access, so it’s really helpful to open the website files in Firefox and browse away.

Other people I know use more complex workflows, like committing the website to a git repository and having a process that automatically builds and pushes the generated website to a server after every commit. That’s way too much complexity for me, I just want to hit a button and see my changes live on the internet two seconds later, I really don’t need to version control anything.

Because Toaster started off as being a program for only me to use, I didn’t have to worry about following standards or how other people think things should be done, I could just focus on making a program that worked well for me. In particular, Toaster uses a much simpler form of Markdown that looks tidier and works better than the various flavours that already exist on the internet.

A better markdown

I don’t think it’s a controversial opinion that there are way too many flavours of slightly-incompatible Markdown out there in the wild. The plethora of options is reassuring in a way, it makes me feel better about concocting my own to suit my own needs.

Here’s all of the changes in my markdown syntax that I can think of:

• Headings are restricted to three levels (# to ###). Every other markdown thing gives you six levels of headings, which is just way too many for a coherent document. The underline syntax with = or - is silly.
• Inline HTML is not supported, it’s messy and ties you to HTML as the only output format. If you do need to inject some custom HTML into a page, there’s an embed-html code block syntax that does this.
• Lists use - as the only bullet character to keep things simple (no * or + for lists). Numbered lists aren’t supported, they’re kind of silly. Nested lists aren’t supported either.
• Bold is *this*, italic is _this_, it keeps things simple. Having multiple variants is silly, and the bold-italic syntax of ___this___ is especially silly. Letters in the middle of a word can’t be styled (so none of t*hi*s mess).
• Notes (‘blockquotes’) can’t be nested, and can’t contain lists or any other block element. Line elements like italics and links are fine.
• Links are split into internal and external links, like how MediaWiki links work. Internal links are {this}, external links are <this>. Links don’t use square brackets, because I use those a lot in quoted text, “like [...] and [also] this”, and they definitely shouldn’t use parentheses (for obvious reasons). Labels on links are optional, using a double-colon <like this::http://benbridle.com>.
• Paragraphs have to be unbroken lines of text. Line-merging behaviour is silly, because it encourages people to break their own lines and make the page source fixed-width, and it makes blank lines more complex.

For extensibility, I use a few different hard-coded code block syntaxes that turn into what I need. The recipe syntax, for example, is used to turn a recipe formatted like Cream {butter, 200 grams} and {sugar, 1/2 cup} into a nice ingredients list and method, and the gallery syntax takes a list of image paths and generates an image gallery. If I need something else, I just edit the program to add a new special-case syntax.

If you’re interested in what the markdown syntax looks like for any page on my website, you can add a .md extension to the page URL to see the original markdown for that page (try benbridle.com/debrief/a-brand-new-toaster.md, for example).

Other people

Toaster was originally just for me, but I published it anyway because I like to put my work out into the world. Publishing my work always improves the work, because it takes a little bit more effort to polish it up and write a landing page and manual.

After a while my partner started using Toaster as well, so I smoothed out a couple of rough edges, and a friend asked about it recently as well so I made it a little more general again. It’s finally turned into something that other people might not regret using, so it needed a sort of logo image thing for the project page. I don’t think that projects are really complete until they have a nice picture to set the mood.

I had a lot of fun hacking up a couple of pieces of toast to make this. It’s kind of a silly picture, but it should be, Toaster isn’t the sort of project that needs to take itself seriously. It’s just a little tool I made for myself, after all.

Thanks

Thanks everyone, your support for my work means a lot to me. Catch you next week!