On Proper Markdown Usage

Reading time
3 minutes

Well, the title sounds presumptuous, but what I want to state is simple: don’t write Markdown in a way, which ties you to a certain platform or software.

The beauty of Markdown – ignoring the great simplistic way of writing HTML pages – is the portability. But if you cannot use your Markdown as a drop-in without changes for a new blogging engine, for example, then it’s not portable.

Having wiki-style links in Markdown ([[link]]) to other local pages limits portability.

Having links with attributes like for kramdown, a Ruby Markdown parser, limits portability. (![Image title](image.jpg){: loading=lazy})

Having frontmatter like in Jekyll limits the portability.

I’m guilty of using frontmatter myself, because without frontmatter, some pages won’t be processed by Jekyll and subsequently being served as downloads. But I’m not happy about it.

I use filenames for my blogpost like this: yyyy-mm-dd-slug.md, which is the mandatory Jekyll way, but which I also like very much. Because I have a couple of expectations of how my blog should look like, I have to use a lot of entries in my frontmatter.

  • title: Without it, the title would be the slug without date and hyphens. E.g. Wow, I’m Live! would become Wow Im Live.
  • date: I want my posts to be sorted chronologically, so I need the time as well. Otherwise they would be alphabetically sorted for the same date.
  • permalink: I only want my URLs show the slug (e.g. https://domain.tld/on-proper-markdown-usage).
  • excerpt: I use manually created excerpts as <meta> description for SEO and for displaying them next to the post link on index pages, so people know if a post is of interest to them. Cute titles and automatic excerpts don’t suffice.
  • categories: I link those in a menu to make it easier for people to find the posts they are actually interested in.
  • tags: I have them, but don’t expose them on the website. They are helpful for algorithmically finding related posts, which I currently don’t use.
  • redirect_from: To redirect old URLs.

Looking at these attributes, I think categories and tags are optional.

I’m also guilty of using {: loading=lazy} to enable lazy loading for images, which is great for data transfer limitations. Fortunately, this can easily be removed with a global search and replace using a capable text editor when changing blog engines.

But I really would like to not have frontmatter. Or, at least, have the title be in the content section as the most important heading. Then it would be easy to remove the frontmatter and just keep the content.

I also use GitHub-flavored Markdown (GFM), which is based on CommonMark, and adds – most importantly – table-support. The original Markdown by John Gruber is stagnent since 2004 and didn’t age well, although I used Markdown quite early.

While this can also be a problem, I think the default Markdown should be GFM, because a proper standard (CommonMark) and table support (GFM) is not unreasonable.

I really would like to have blog engine, which has no meta data in Markdown files, uses the date from the filename, but still only uses the slug for the URL, and uses the first line as the title.

Then I would have not categories, tags and redirects, which is acceptable from a minimalist’s perspective. But losing the excerpts? Ouch. Maybe I should incorporate those in the first paragraph of a post and style it accordingly.

Subscribe to updates via RSS feed or via JSON feed