On Proper Markdown Usage

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. (`{: loading=lazy}`)

Having front matter like in Jekyll limits the portability.

Front Matter

I’m guilty of using front matter myself, because without front matter, 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 certain expectations of how my blog should look like, I have to use a lot of entries in my front matter.

title: Without it, the title would be the slug without date and hyphens. E.g. “Wow, I’m Live!” would become “Wow Im Live”, because it’s not feasible to express some reasonable title characters in a filename on most operating systems.

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 to show the slug (e.g. `https://example.com/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 on hosted platforms, where I don’t have access to the web server’s redirect config.

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 front matter. Or, at least, have the title be in the content section as the most important heading. Then it would be easier to remove the front matter to 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 has been stagnant since 2004 and didn’t age well, but it was great when I began using it in 2008.

GitHub-Flavored Markdown

CommonMark

Original Markdown by John Gruber

My Early Markdown Usage

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 a blog engine, which has no metadata 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 not have 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.