Simple single-executable Blog generator

This blog lists what I want from a blog generator, and shortly shows how I've achieved all my requirements, which – unfortunately – made me write a custom tool. The post in itself doesn't have a lot of value but I cannot test my fancy new tool without a first post.

In my past job, I found it increasingly useful to write RFCs. They helped me explain things to colleagues and even more importantly, made it easy for me to go back and revise the reasons behind certain decisions I made. As I am self-employed now, I want something similar and am thus trying myself at blogging.

What I want from a blog:

  1. Cross-post: Cross-post to dev.to and hashnode.com, but point the canonical URL of those posts back to a self-hosted blog so that I can easily hop blogging-platform while keeping the canonical source unchanged.

    I was thinking about just using one of them, but couldn't decide between them. The same decision might come up again over and over once new and similar communities arise. So using both and having a self-hosted canonical source is the perfect solution in my opinion.

  2. No Comments: Don't add comments or similar interactions, the above cross-posts can act as a way to engage with others.

    I don't want to deal with the privacy-related consequences of those features/interactions. Having the interactions on other platforms is sufficient for me anyway.

  3. Static: The build result of the blog should be a completely static webpage so that the deployment can be a simple upload to a CDN.

    I totally buy the approach of setting a CDN before a server that dynamically renders pages (so that you basically have a static webpage once the CDN is hot). Though, creating the statics on built-time is still a simpler infrastructure for me, which is why I prefer it if possible.

  4. No JavaScript: No JavaScript at all, or avoid JavaScript as much as possible.

    Just wanna read a blog post right? There are no interactive elements on the page right? Well, let me quickly hydrate the page with Framework X anyway!

  5. Just Markdown: I just want to run a single standalone CLI against a set of Markdown files and call it a day.

    There are plenty of open-source static page generators I could choose from. But all I want to do is the following:

    blog-generator --site-name "My Blog" ./*.md

    No blog-generator init to set up a specific directory structure, not having to add a theme, not having to add a layout, blog index template, or blog entry template, ... Just. Markdown.

  6. Single-executable: I want a single static executable to build the blog.

    No offense to anyone, but I am personally so done with things like npm install just to run a tool.

  7. No customization: No is exaggerated as I still want to give it a custom name and add links to Github and Twitter, but I neither want to deal with a custom theme nor setting up a custom HTML scaffold.

    I might grow old, but I really enjoy using things like Rust documentation, mdBook (common in the Rust ecosystem) and the Golang docs, where every page regardless of the crate/package/project looks and feels the same as I don't have to re-learn a new webpage for every dependency. I'd love to have the same for blogs, where almost every self-hosted blog out there looks and feels the same. This will most certainly never be a widespread thing for blogs though.

After several hours of searching, I gave up the search for such a tool. I was either unable to find a tool like that, or such a tool simply doesn't exist. mdBook comes very close, but is specialized for books/tutorials.

So as a dev, well... I ended up building the tool I want over the course of a day (at least the initial POC). You are reading the build output of this tool right now. The initial implementation ended up at around 500 LOC in Rust - not that this is really a useful measure or information.

This is how I solved the requirements I had:

  1. Cross-post: Cross-posting will be done manually, especially since I don't want to cross-post everything.
  2. No Comments: I didn't add any comment feature, so: achieved.
  3. Static: The CLI works exactly as shown above and outputs a set of static files. I am deploying to Cloudflare Pages.
  4. No JavaScript: There is exactly none JavaScript used. The syntax-highlighting, which a lot of blogs do on the client-side via JavaScript, is done during build-time using the excellent syntect crate.
  5. Just Markdown: The CLI works exactly as imagined above and outputs a set of static files. I made it so that I can pass configs like the site's name with either a command line flag or an env variable. This allows me to adjust those settings via env vars in the build configuration of Cloudflare Pages (or Netlify, Vercel, ...).
  6. Single-executable: The tool is written in Rust (Golang would have worked well too) and all static assets like the HTML scaffold and CSS file are embedded into the resulting executable.
  7. No customization: I didn't add any theming support, so the tool is completely opinionated. I'll probably fine-tune the look and feel in the future to make it more appealing to a wider range of users. I have no interest in adding theming in the future - except maybe color schemes. The only things that can be configured right now are the site's name, your Github handle and your Twitter handle. More similar settings might come in the future (like an accent color).

The tool can be found here: github.com/rkusa/mdr (though it doesn't even have a README yet)

As always, the first 80% were easy, the final 20% of fine-tuning will take a while. If I end up writing posts regularly, I'll also invest more time into the tool and finish it up into a state that could be useful for others. Let's see.