You Should Probably Blog in Markdown

April 27, 2016

Maybe you’ll read that title and think:

Damn, Chris. Little dogmatic isn’t it? There are lots of ways to do things, especially on the web. Why be all prescriptive?

You’d be right. What I actually want is for everyone creating content on the web to create that content in a clean way that will serve them long into the future. Markdown, I feel, highly encourages that.

Let us explore some of those ways.

If you have no idea what Markdown is, it’s a “text-to-HTML conversion tool for web writers”. It’s root is here and there are many implementations.

1) It keeps dangerous cruft out of your content

This is #1 for a reason. I overflow with sadness when I hear of someone dealing with legacy content that is full of ancient markup.

I bet you know what I mean.

Things like <span style="font-weight: bold; font-family: Georgia; color: red;"> around seemingly random sentences. <div class="content-wrap-wrap"> wrapping every single blog post because it was just “what you did”. Images force-floated to the right because that made sense three designs ago. Headers with class names on them that don’t even exist anymore. Tables of data spit into content with all the whitespace stripped out and weird alignment attributes you barely recognize. An about page that was pasted in from Microsoft Word.

Content like this will not and cannot last.

A frustrated person in the future might just delete it. Someone might be forced to clean it up in the future, become even more frustrated, and do a bad job of it.

It discourages and delays more important work.

To be fair, most Markdown implementations allow HTML, so you could junk up content system that supports Markdown too. But, the support of Markdown highly encourages using it exclusively. Plus you could make it a rule in your organization.

The point is: when you blog in Markdown, you’re writing in a clean language that translates to very clean HTML. Just your standard <p>s, <ul>s, <ol>s, <blockquotes>s and the like. Good ol’ semantic and accessible content.

2) It encourages structured data

Say one of types of pages on your website needs to have a hero image at the top. Another one needs a thumbnail gallery of images. What then? There is no Markdown standard for these kind of things. Aren’t we then forced into some kind of <div class="hero-banner"> or <div class="thumbnail-gallery"> situation?

What I mean is that your CMS should be helping you here. You need a new page type that your CMS knows about that allows you to store data that accommodates the needs of that type of page. The thumbnail gallery shouldn’t be inside the “chunk of content”, but rather in some kind of organized custom field area that can be accessed and used by the templates.

3) It can be compiled to other formats

I don’t really see HTML going anywhere on the web anytime soon. It’s been the most constant tech on the web for as long as I’ve known.

Still, perhaps it will change one day. If it does, you’re in luck. If you’ve been working in Markdown, you’ve been working in an abstracted language all along. Markdown typically converts into HTML but there is no reason it can’t convert into something else instead.

Plus, think of all the custom formats out there. I’ve been looking at Apple News lately. To publish to Apple News, your content needs to be in a special JSON format, and the content inside that expects (you guessed it) Markdown. If it needed something else, you can bet there would be a converter available.

4) It encourages keeping the site fresh

You can easily gather enthusiasm for a site redesign (or freshening up) when the infrastructure for the site and its content is sound. A project could become “let’s update our typography system to accommodate the new branding and address the widening spectrum of devices” rather than “ughck we need to clean up a decade of inline styles before we can create a type system that actually properly applies itself to our content.”

5) It feels good to write in

Once you’re used to it, it feels very natural. Far less awkward than reaching for those angle bracket keys. I particularly like the link format, where you can write out the text you want to be linked first (within the square brackets) before you need to stop your brain for a second to go copy/paste the link.

Right then.

I’ll bet you a nickel you don’t regret it.

If you end up not going with Markdown, I’d still highly encourage very clean HTML markup, or something else with the same kind of advantages I describe here.

Author

Chris Coyier

Chris is a web designer and developer. He writes about all things web at CSS-Tricks, talks about all things web at conferences around the world and on his podcast ShopTalk, and co-founded the web coding playground CodePen.

Comments

You won’t regret it, but the truth is it does limit you. Possibly for good, possibly not. Chris has been advocating for this for a while now I’m assuming because he’s fed up of people whining asking him to migrate difficult content. The truth of the matter is there are many ways to achieve the same ends. Wrapper blocks are one such method. Past versions of a site are another.

I have to say my personal feeling is that if your content is 10+ years old and you don’t run a library, research institute, or educational institution in a slowly moving, established field; then you probably believe it is more valuable than it is. In any case updating it won’t hurt and is a micro-optimization on time, where there must be something to add, some note or advance or tid-bit that would make it better…

Chris isn’t wrong, but he’s certainly come to different conclusions to me

Adam

And Dory, which is a universal React blogging platform I’m working on. I do plan to release some videos soon that I’ll post to Reddit, as it’s very easy to setup. Dory of course uses Markdown! https://github.com/Wildhoney/Dory

Surely this only applies to people not creating and storing their content in a properly structured way (ie wordpress theme users)? If I deliver a CMS driven project to a client, whether using ExpressionEngine, Craft, Statamic, Processwire or Bolt – I make sure that they can write and publish the content how they like whilst only using standard html markup (ie no additional classes or non-semantic cruft). That way their articles are stored in a clean, portable, marked-up way, not as something that needs parsing before it makes any sense. And it means that they don’t need to worry about whether or not they’ve left a trailing space, or how many **’s to use, or how to format that numbered list. I’m not convinced, but I do love your site and use it regularly for reference Mr Coyier

Tim

Personally I use markdown every day, writing blogs, fiction, etc. Hell even my shopping list is in Markdown.

The problem I face though is that it never found a platform that quite encompasses everything I need from a portfolio site (as a writer) and still get drawn back to WordPress for its plugin/app centric methods.

That said I’m totally open for ideas on what platform to use. The trade off I have is while I can code something custom, that takes me away from actually doing the thing I love, which is writing content.

There are only two things that stop me from investigating further, one is that as I write in Markdown using a few tools a primary want/need is to post via Dropbox (upload then auto-publish). The second thing is the sheer price point. $99 doesn’t seem like a lot of money, but if I’m going to spend AUD$132.70 just for the luxury of Markdown, I need to make sure it fits my processes which I have little time to do.

Bulo

Hi Tim, forget about Dropbox, there is a new simple toll for you to publish and share your Markdown – http://markdowntoweb.com

While everyone seem to love Statamic, there are a few similar flat file cms’ for free.
The most promising one is Grav: https://getgrav.org
Grav has many plugins and themes to get started and (from what I tried so far) it can do a lot.

chaoaretasty

I’d argue “markdown or other similar markup”. We took the decision to use a mediawiki based syntax, while I generally find markdown nicer we’d had a mediawiki internally for many years so I wanted to make sure users didn’t have to know two syntaxes.

In a perfect world where software bugs don’t exist I would love to blog in MD, but unfortunately that is not the case so I find myself having to switch to HTML in order to make the content more portable. If you blog heavily in Tumblr MD you’d know what I mean. For example, try copying complex MD with lots of code samples from Stack Overflow and post it on Tumblr, then go back and edit that post — you’ll find that sometimes the formatting is not preserved. (Tip: Whenever this happens, you can preserve the formatting by converting MD to HTML before saving the post.)