This weekly debrief is for paying supporters of my work. Please only read if you've <paid::https://patreon.com/benbridle>. Thanks!

```embed-html
<details id='paid-toggle'><summary class='button centered'>→ Click here if you've paid ←</summary>
```

---

This week I released a new version of {/Projects/Toaster}, my website generating program, and wrote a better {/Projects/Toaster/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 <https://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:

!<Old screenshot of my website on breadpunk.club::/images/breadpunk-toast-index.png>

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::https://www.mediawiki.org/wiki/Help: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 <https://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.

!</images/toaster-banner-tagline.jpg>

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!



```embed-html
</details>
```