I wanted to quickly link between blog posts. Since I use VS Code, we can abuse user defined snippets to support this feature.

This is the end result:

Generating the snippets in VS Code's JSON format

After some experimentation, this is the target format:

{
  "A few system design \u0026 architecture experiences, low-level debugging stories and post-mortems": {
    "scope": "markdown",
    "prefix": "@@interesting-reads - A few system design \u0026 architecture experiences, low-level debugging stories and post-mortems",
    "body": "[${1:A few system design \u0026 architecture experiences, low-level debugging stories and post-mortems}](/interesting-reads) ",
    "description": "A few system design \u0026 architecture experiences, low-level debugging stories and post-mortems"
  },
  "A grep-quickie for the road (or svn, really)": {
    "scope": "markdown",
    "prefix": "@@a-grep-quickie-for-the-road-or-svn-really - A grep-quickie for the road (or svn, really)",
    "body": "[${1:A grep-quickie for the road (or svn, really)}](/a-grep-quickie-for-the-road-or-svn-really) ",
    "description": "A grep-quickie for the road (or svn, really)"
  },
  // ...
}

Good ideas:

  • Put the generated snippets file in .vscode/posts.code-snippets of your blog's repository.
    • Keeping it local to a git repository keeps everything nice and tidy. No suggestions for your other repositories.
  • Use a common starting string, @@, for all snippets' "prefix".
    • We want some way to only get suggestions of blog posts.
  • Spam keywords in "prefix".
    • VS Code's fuzzy auto completion only matches against "prefix". "description" is decoration only.
  • Provide a default for the link text (to the blog post title).
    • In body text, the link text will almost always be removed, but having a writing prompt is not too shabby.
    • VS Code smartly pre-selects the default, so there's no cost of just starting to write something completely different.
  • Put a trailing space in "body".
    • Allows for quickly continuing to write. If the link is at the end of a sentence, you need to follow up with a backspace. So be it.

All it takes is a loop to generate the snippets, which is done while generating the HTML of the blog posts.

By regenerating the snippets for each build of the blog contents, we make sure that the snippets' URLs & titles are up to date.

Postscript, on motivation

I'm trying to get over my private org mode file usage and "blog" more. wc reports 240k words, in comparison to only three blog posts between 2013 and 2024.

One part of this effort was to make the blog engine a bit more lightweight and custom, so I wrote a new one.

Another part was to find a quick way to refer to sibling blog posts here, when writing markdown.

Zettelkasten (small notes and a giant web of internal links) seems to be super popular. There are many plugins supporting this, it sounds a bit like gf in vim), but I figured that each markdown post's permalink would be unique & stable enough to use as a target.