Don't use Markdown for blog posts

Full disclaimer - I don't mean to ruffle any feathers so before you pull out your pitchforks, this article is about using markdown for publishing blog posts using static site generators.

This is not about markdown as a data format for writing articles.

Context

Way back in 2019 when Snapfont was being built, I needed a blogging mechanism to post about various topics. Since I wanted to keep everything clean, I decided to go with raw markdown files for Snapfont's blog posts.

This decision was based on:

• Simplicity - I don't need to install nor setup a 3rd party CMS or application and write my blog posts there.

• Markdown - Anybody can learn to use it in a few minutes. And even if you forget how to use it, there are heaps of markdown cheatsheets you can reference from.

• No installation required - I mean, I did need to install nuxt-content and style the post pages, but apart from that, there's nothing extra required from my side.

• In vogue - Since everyone on twitter and hackernews is using markdown powered static site generators, let's be part of the cool kids club and start using it.

And the trouble began

Markdown is great and all but some things like images are need manual intervention. I had to create the image in Figma and optimize it, pull the image file to my server's static folder, link it in markdown and then save the blog post.

I also wanted custom components like an automatic table of contents section or something similar but this wasn't possible without more coding.

Lastly, I needed my nuxt repo setup running whenever I wanted to write something. This is a big inconvenience when you just want to jot down an article's outline while on the road or when you're laptop's not available.

Because of this crummy workflow, I got lazy and stopped posting anything altogether.

What am I using now?

I moved my publishing to a headless CMS(DatoCMS). I can go into more details about Dato - but really any headless CMS like Directus, Keystone, etc will suffice.

Immediate benefits are:

• I don't need to be on my production laptop to publish posts. I can start writing as long as I have an open browser and an internet connection.

• No more crummy workflow. Need to use images? Just drag and drop them. Want to turn a text into a link? Just past your link or highlight a line and paste your link in the popup.

And as a result, my blogging workflow and productivity has increased massively.

Conclusion

Markdown based blogs sound great on paper but it leads to a very clumsy authoring workflow. I think it's worth pondering over why markdown based blogging workflows are so popular, especially on hackernews and other tech communities.

For starters, most people would use the built-in notes app to jot down their thoughts. For programmers, we find it more natural to open up vscode or any other idea to start writing.

Secondly, this workflow got popular around building small jamstack websites which were really small and more commonly used for personal blogging rather than serving the needs of a startup or a money making blog.

Lastly, these tech communities are an echo chamber and anything you read there should be taken with a grain of salt. Just because it's in vogue, doesn't mean its good.

Notes:

• Markdown is a very simple text format for writing articles. You can use any text editor to write Markdown but there are some specific editors that can make it easy to preview Markdown text.

• Jamstack websites are simple file based html websites that are heavily powered by javascript. Typically they don't have a backend. This site(that you're reading this on) is a jamstack website.

• Headless CMS are backends that don't have a frontend. Think of it as a Wordpress setup that only has the wp-admin area, no frontend, no landing pages, nothing.