CraBlog

Hello, and welcome to my blog! This specific post will be talking about CraBlog - the tool I made to create it.

I wrote CraBlog over about a week. While I intended on it just being a simple script, it eventually gained a bunch of features, and I polished it to a state where I could release it to the public. As of now, these are:

When I make stuff, even for personal use, I have a tendency to polish it up to the point where it feels like a project intended for a wider audience, and that's kinda what happened here lmao. Initial prototypes were super hardcoded and panic-happy, then I started adding features like config files and pretty errors, and decided I should try to polish it up for a release on crates.io. So thats what I did.

Choosing a templating engine

CraBlog uses a tool called pulldown-cmark for transforming markdown into HTML. However, while the output is a valid HTML sequence, it is not a valid HTML file.

For example, consider the following markdown:

# Hello, World!
This is a markdown document.

When passed through pulldown-cmark, the output looks like this:

<h1>Hello, World!</h1>
<p>This is a markdown document.</p>

However, for the output to be a valid HTML file, it would need to look like this:

<!DOCTYPE html>
<html>
	<head>
		<meta charset="UTF-8">
	</head>
	<body>
		<h1>Hello, World!</h1>
		<p>This is a markdown document.</p>
	</body>
</html>

And that is just the bare minimum you'd need for it to be valid - typically, you'd also want a CSS stylesheet, elements like sidebars or headers, and meta tags like Open Graph protocal properites, all of which will vary significantly between different websites.

The solution? A templating language.

Templating languages are languages which allow you to replace text within a file. By using some simple syntax and a bit of structured data called a context, you can insert text into a preexisting document at whatever point you want. Perfect!

However, Rust has a lot of templating languages available, and many dont fit my usecase. Particularly, many require you to embed your HTML into your Rust code and do the templating at compile time, sending us back to square one. I also wanted to minimize the number of dependencies (to keep the binary size and compilation times small) and to keep the templating language itself simple, which made choosing one a bit trickier.

Initially, my choice was Mustache, which is one of the simplest options available. This worked fine for single variables, but I eventually decided to add lists to the context, and Mustache's syntax for lists is prety weird, so i decided to choose something different.

The options I considered were:

Tera and Liquid were the first two I tried, but both brought in a massive amount of dependencies that would have significantly increased compile times. TinyTemplate was closer to what I was looking for in terms of scope, but had its own issues - it expected the templates to be included in the binary itself, meaning it needed a 'static lifetime and I would likely need a hacky technique such as Box::leak to use it. In the end, I eventually settled on Minijinja - while it is a bit more complex then I would have liked, it checks all the boxes I wanted, and is nearly identical to the more popular jinja2 templating language used in the Python ecosystem. Ultimately, I am happy with Minijinja, and I think it was a good choice for CraBlog.

Not so simple syndication

Typically, most normal people aren't going to be checking every single blog they know of all the time. Blogs may be updated infrequently, and people's memories are pretty flawed.

To solve this, blogs can use something called syndication to share their posts. Syndication means that their content can be viewed in other places, such as another website or a dedicated app (for example, Newsflash if you're on Linux). This means if users find a cool blog, they can simply take a link to a site's syndication file. In fact, a big part of why CraBlog was created in the first place was so that I could automatically create and update my syndication file, so that I wouldnt have to duplicate content or remember to update it whenever I create or update a post.

The problem is that there isn't just one type of syndication. The most popular type is RSS, but there is also Atom, and some more niche options like JSON feeds.

CraBlog offers its syndication using Atom files, with no option to use any other format. While Atom is a less well-known standard than RSS, it is widely supported, offers a nearly identical featureset, and has some technical advantages over RSS. RSS provides no benefits over Atom, and would only serve to add extra complications.

Closing thoughts

That was my deep dive into CraBlog, my blogging software! If you want to download it yourself, or look at the source code, you can find them here: