Microfeatures in my blog ★

Published and revision info

There’s a trend for blog posts to not include the date the post was published—and I hate it, especially for technical content. I don’t even like to call the date of publishing a “micro” feature as it’s more an essential feature.

Regardless, I include the published date below the post title in my blog:

I also think it’s valuable to display the date the post was updated:

I guess it would be more precise to manually specify when the post was updated, to avoid changes like Enclose titles in “, now an error after Hakyll update where the post content isn’t changed in a meaningful way. It’s too bothersome to remember though so I rely on the Git history and have a list of commits I ignore when I fetch the dates. Not perfect but good enough I think.

Quote attribution

The only true wisdom is in knowing you know nothing.

Blockquotes are standard everywhere but you often want to show where the quote originates from.

I think it’s nicer to have specific styling for attributes than to solve it manually, like this:

The only true wisdom is in knowing you know nothing.
— Socrates

Different kinds of notes

I’m a fan of sidenotes and I used them heavily in the book I wrote. They’re great for a certain style of content but for the blog I noticed I used them very rarely. Instead I use “notes” of different kinds to highlight certain things:

Maybe a weird thing to prioritize in a post but I really like the additional color splash the notes can give to a post.

I also have footnotes¹ (mostly because Djot provides them by default) but I never really use them. I guess I should use footnotes more now that I have them.

Enhanced code snippets

pub enum Code<'a> {
    Inline {
        code: &'a str,
        lang: Option<&'a str>,
    },
    Block {
        code: &'a str,
        lang: Option<&'a str>,
        path: Option<&'a str>,
        linenum_start: Option<u32>,
        highlight_lines: Option<RangeSet<u32>>,
    },
}

Embedding code into blogs is common practice and I’ve added a few extra features to the code display on my blog:

1. Overlay the language or file path.

   For code blocks there’s a small description that displays the language. It can be customized to for example display the path of the file:

   

   It’s accomplished using CSS with data attributes and ::before, and won’t be visible in the RSS feed.

2. Syntax highlight for inline code elements.

   Highlighting code blocks is standard but I wonder, why don’t we also highlight inline code?

   It’s something I added to be able to refer back to values like "-NoHU", 0, and require("telescope.builtin").find_files() when explaining what happens inside a code block. A sentence with color is much more pleasing than the colorless "-NoHU", 0, and require("telescope.builtin").find_files() don’t you think?

3. Ability to highlight lines.

   code > .line.hl {
     background-color: var(--melange_a_sel);
   }
   

   Benjamin Tan’s excellent blog post about Jujutsu used highlighted lines to good effect and inspired me to implement them.

4. Line numbers with offset.

   code > .line[data-linenum]::before {
     content: attr(data-linenum);
     padding-right: var(--space-2xs);
     color: var(--melange_a_ui);
   }
   

   Line numbers is another feature I’ve recently implemented that I think is a good idea. Them being optional is important as line numbers adds visual bloat. I’ll probably only use them in very specific scenarios where I really want to call out code at certain lines.

5. No images, no JavaScript, and no embedded Gists.

   It frustrates me to no end when someone has made the effort to write a good blog post and then use images for their code. Images inevitably fail to render as crisply as regular text and they’re either too small, too blurry, or impossible to read on the phone.

   I also really dislike requiring JavaScript just for displaying text or embedding code as GitHub Gists. It’s just text—let’s serve it as text.

Table of content

I can optionally insert a table of contents by including a :table-of-content: marker in the markup. It uses the <details> element and is collapsed by default. When expanded it looks like this:

It’s important for me that the table of content is optional as I have a mix of small and large posts. The table of content is generated from the first two heading levels and it works quite well for my use-case.

Flex and gallery display for images

I sometimes want to display two or more images next to each other. Instead of having images embedded like normal I place two or more images in a <figure> and use flexbox to place them next to each other:

When I have more images I use CSS grid to create a small gallery:

Embedding YouTube thumbnails

Click to view on YouTube

The recommended way to embed YouTube videos is to use iframes and it’s something I implemented over a decade ago. It works but it’s not a great solution. Embedding anything from Google is an enabler for their all-encompassing privacy violations and YouTube embeds are bananas heavy.

Instead I embed an image generated from the video (served from my site, not YouTube) and make it a link that takes you to YouTube. I could’ve used JavaScript to convert the placeholder into an embedded video when clicked but I like simplicity and redirecting to YouTube allows third-party players to handle the redirect.

Different list types

I like lists and I have several different types I can use to mix things up a bit.

Here are some ordered list types:

1. One
2. Two

1. Alpha 1
2. Alpha 2

1. Roman 1
2. Roman 2

And here are some unordered list types:

• Bullet

Necessary? No.
Fun? I think so.

Unbroken indexes of all posts

Under /archive I have a list of all posts so it’s easy to scroll through and get an overview of what I’ve written about during the 15 years the blog has been active.

Naturally there’s no pagination so you can just scroll through. I only have 279 posts… What’s the point of pagination anyway?

There’s also indexes for tags (see keyboards) and per year (see 2023). The yearly index mostly exists so I have an easy way to see the past years posts when I do my yearly review.

Featured & favorite posts

Highlighting favorite posts is a good idea I got from the Hacker News discussion and one I just had to implement after seeing it. I handle featured and favorite posts in three ways:

1. I list five featured posts on the homepage:

   

2. All favorite posts are listed under /favorite.

3. Each favorite post is accompanied by a star: <span class="favorite"><a href="/favorite">★</a></span>

   

   Clicking on the star takes you to /favorite.

Series

Tags are fine for grouping slightly related posts but sometimes posts follow a more structured story, which is where series come in.

A good example of a series is the Let’s build a VORON Trident where I document my journey of building my first 3D printer over 12 posts.

There’s a few features that come with a series:

1. All series, both ongoing and completed, are listed under /series.

2. Each series gets a separate page with a description and the list of posts.

   See /series/voron_trident or /series/t-34.

3. A post is clearly marked as belonging to a series.

   It’s marked next to the post title:

   

   And more information about the series is included at the end of the post, so it’s easy to jump around in the series:

   

4. Selected series are showcased on the homepage.

I like series and I want to write more series. The drawback is that they take more effort to create than standalone blog posts. As my attention and motivation tends to shift a lot this increases the risk of stress if I lose motivation in the middle of a series.

Projects

While a blog is about writing I also wanted to highlight some of the personal projects I’ve made.

There are no individual pages for the projects as they typically live outside this site (maybe at GitHub). Instead I have a /projects page with the projects and I include a subset of those on the homepage.

The projects markup is fairly simple, just a title and a description (that could include an image, code block, or whatever):

Long ago I made some game prototypes and I wanted to showcase them in a slightly different manner. They’re still included as a project but they get specialized markup that I’m pretty happy with:

Automatic dark mode

Because I have a preference for dark mode I really wanted a dark mode for the blog, while also catering to people that prefers a light mode.

I implemented dark mode using prefers-color-scheme, a simple solution that doesn’t require JavaScript and “just works”. It’s a CSS feature that allows the user to specify their preference using the browser or operating system.

Targeted RSS feeds

RSS feeds are awesome and I think all blogs should have them (and news sites, social media sites… almost everything really). I do of course have a feed but it might be a good idea to add specialized feeds such as:

• Feed for a series
• Feed for a tag

The only reason I don’t have them is laziness.

Search

Because it’s a static site it’s harder to have a good search functionality. Maybe there’s a good way to create/include one but I haven’t looked into it more.

A better 404 page

Perhaps related to the search functionality, it would be nice if the 404 page would include a helpful “did you mean” message.

For example if you typed in the path /use it could suggest you to try /uses instead.

So far I’ve avoided JavaScript in the blog but here it would be nice to have.

Summary of a post

I’ve toyed with the idea of having a summary of each post, so I could have the summary of a featured post on the homepage. However, good summaries are cumbersome to maintain and hard to auto-generate.

I don’t want to summarize manually—it introduces too much friction into blogging. While LLMs are honestly quite good at generating summaries, I think we need less AI generated content on the web, not more. Taking the first N characters or M paragraphs is a shoddy way of summarizing a post and won’t create a useful summary.

While I like the idea of a post summary, it’s not a feature I’ll implement anytime soon.

Display “related” posts below the post

Another interesting idea is to display a bunch of related posts at the end of a post. The problem is similar to that of summarizing a post: it’s cumbersome to maintain or hard to auto-generate well. For now I’m content with tags and series as a means of grouping related posts.

Changelog

While I display the latest Git commit for each post I was impressed by the list of “meaningful changes” at the bottom of the jj init blog post.

A changelog looks cool but I’m too lazy to maintain one for all posts. A post like The current T-34 keyboard layout would probably benefit from a proper changelog.