Initial post

This is the first post on this blog, and I want to take the time to (shortly) describe how everything works (and what works at all). Maybe you’re curious to see what I have cobbled together; but mainly, this is for my future self, for when I want to improve on this first setup.

Static site generation

Individual posts are written in Markdown and then converted to a static HTML site using custom templates and Zola. Zola is an opinionated static site generator, and I like its opinions. Also, because it is written in Rust, I may be able to contribute fixes and/or features if I’m unhappy with it. It’s been a while since I’ve made the choice for it (I did the initial setup for this blog way before I found the motivation to actually write this post), so I can’t really compare it to the popular alternatives and tell you what the reasons for my choice were, but right now I can happily recommend it. Honourable mentions of other considered static site generators are Hugo and eleventy.

I don’t have a lot of experience designing websites, so I’d like to thank Paul Hennig for helping me with the templates (both making me aware of best practices and tweaking the CSS so everything looks like I want it to).

Showing off

Let’s see what fancy stuff I’ve been able to make work.

Code blocks

This is a programmer’s blog, so code blocks were a top priority. There are inline code blocks, like this, and also dedicated code blocks with syntax highlighting (these are supported out of the box by Zola):

pub fn main() -> Result<(), String> {
    std::borrow::Cow<_> _ = "moo".into();
    if 1 + 1 != 2 {
        Err("uh oh".into())
    } else {
        Ok(())
    }
}

The relevant part of my Zola config looks like this:

# Whether to do syntax highlighting
# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
highlight_code = true

# The theme to use for code highlighting.
# "css" uses CSS classes instead of inline styles.
highlight_theme = "css"

# For these themes, CSS files are put into the static directory.
highlight_themes_css = [
  { theme = "dracula", filename = "css/dracula.css" },
]

The little indicator for the language on the top left of the block needs to be manually added to the CSS for every language, but as that’s only needed once and I’m not going to use that many different languages on this blog, I’m fine with that.

All in all, I’m very happy with how code blocks look. The only thing I couldn’t find out is how to make Firefox respect the inner padding of the code when there’s a horizontal scrollbar (the longest line then has no padding on the right). I think this is a bug in Firefox, at least it works in Chromium-based browsers.

Text formatting

Bold text works, of course, and italics as well. If you write an ellipsis (three periods), it automatically gets converted to a single unicode character… Plain “quotation marks” are also converted to fancier characters. The last two aspects can be enabled by setting smart_punctuation = true in Zola’s config.

Footnotes

Footnotes are also possible.¹ Even more than one!²

I’ve adapted a script from a helpful GitHub user to improve the footnote user experience. It inserts backrefs for footnotes, i.e. a little ↩ at the end of a footnote that takes you back to the paragraph where the footnote was referenced.

It also changes the references from anchors to buttons (which are styled like anchors), because scrolling down to footnotes and back up again happens via Element.scrollIntoView(). This way, reading footnotes on mobile doesn’t interfere with navigation using the back button/gesture.

If you take a look at the HTML for footnote references, you’ll see the result of some tinkering I did to make sure there are no line breaks between a foot note reference and the text directly preceding it. This is also done in the adapted script: it goes through all the footnote references and splits off everything after the last space in the preceding text into a separate node, which is then put in a <span> that has white-space: nowrap; set, together with the <sup> for the reference.

Images

Images say more than a thousand words, so I’ve written a macro, or as it is called in Zola’s lingo, a shortcode, to insert an image together with its alt text and a caption.

The following short code was used for this image:

{{ img(
    name="ferris",
    alt="Ferris, the Rust programming language's unofficial mascot",
    caption="Ferris, the Rust programming language's unofficial mascot ([image credit](https://rustacean.net))")
}}

Currently, only WebP images are served (converted using Squoosh); I’m not sure if I’ll leave it like that.

Sidenotes

For content that is not strictly relevant, but deemed too important to be banished to a footnote, I’ve written another shortcode for sidenotes.

Fonts

I experimented with different fonts for the text, but in the end I settled for something very basic: Roboto for the headings, and its serif variant Roboto Slab for the regular text.

The code font was immediately decided though (thanks to fasterthanlime): Iosevka.

Post tags

Posts can be tagged with arbitrary strings, although putting spaces in tags seems to break some things.

# The taxonomies to be rendered for the site and their configuration of the default languages
# Example:
#     taxonomies = [
#       {name = "tags", feed = true}, # each tag will have its own feed
#       {name = "tags"}, # you can have taxonomies with the same name in multiple languages
#       {name = "categories", paginate_by = 5},  # 5 items per page for a term
#       {name = "authors"}, # Basic definition: no feed or pagination
#     ]
taxonomies = [{ name = "tags", feed = true }]

There’s a page with all tags and a separate page for each tag listing all posts with that tag.

Atom feed

Zola supports generating an atom feed that you can import into your favourite feed reader:

# When set to "true", a feed is automatically generated.
generate_feed = true

You can find this blog’s feed at /atom.xml. There’s also a separate feed for each tag at /tags/<tag>/atom.xml. All pages have a <link> to the feed (tag overview pages to the tag’s feed) to enable autodiscovery.

Inspirations

My favourite blog is fasterthanlime’s, and I’ve taken the liberty to adapt some of the blog’s layout for my own, as well as parts of https://compilercrim.es’s layout.