in ,

swyx Writing | 6 Things Markdown Got Wrong, Hacker News

swyx Writing | 6 Things Markdown Got Wrong, Hacker News

John Gruber’s Markdown is almost a perfect content authoring format. Here are 6 things it got wrong (in my opinion, of course).

This post is an expanded tweet 1. Lazy List Numbering

In Gruber’s original spec, this was the way he explained it:

If you instead wrote the list in Markdown like this:

design philosophy of Markdown . In practice, more people will reorder their numbered lists just to make it look right in markdown (either manually, or with tooling).

I can understand why Gruber went for it: HTML itself is pretty lazy. Normal li elements don't care about what order you leave them in:



    . Bird . McHale *. Parish - this would show as "

     2. Code Blocks 


    Code Blocks probably aren't necessary, and overlap with 2 important commonly used (but not headline) Markdown syntax features.

    Just to be clear what we're talking about - Code Blocks are how you indicate code ( with 4 spaces), whereas Code Fences are the thing more people probably use today (with triple backticks).

    Here's how Gruber Explained them in the spec


    Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both



    To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab. For example, given this input:

    This is a normal paragraph: This is a code block.

    Markdown will generate:


    this is definitely javascript! and line highlighting

    was probably a step too far for Gruber's goals, but the core idea is that code fences are more extensible than code blocks - and, it turns out - useful for readers of the unprocessed markdown too! This blogpost you just read would be unreadable - and therefore unwritable - without code fences.

    Code Blocks have another related, smaller problem - they coincide with hanging list indents. Here's how Gruber described list indents in the spec :

    To make lists look nice, you can wrap items with hanging indents:

This is pretty handy for the many cases where Markdown just doesn't give you enough control (more on that later). But sometimes you just want to define some wrapper components, and then use Markdown for the rest:

to the rescue. This is EXTREMELY useful for the one stateful UI element offered to you by GitHub - the details / summary tag:

## Docs for my new startup This is my startup! Short and sweet pitch here.

and replied:

markdown=“1” as a tag attribute is the way to solve # 4 properly. But there's a question of how you should handle block vs span elements.

So this is a solution I was not aware of, but it seems it is a nonstandard attribute so it is not in wide use.

The next 2 points are common usecases that necessitate "de-opting" from Markdown, causing the need for Inline HTML in the first place - if we just had these 2 things we would be able to stay in Markdown a lot longer.

4. No Syntax for Adding Classes

There are only 2 mentions of classes in the entire Markdown spec. That's probably not a surprise - as it says


The idea for Markdown is to make it. easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

ltimately, I think, Markdown cannot be fully orthogonal to HTML, and it doesn’t really try to be. It isn’t a design goal of Markdown to let you do everything you can do with HTML, but still it is essentially a language that compiles down to HTML.

Additionally, normally everything Markdown does is visible to the end user – it doesn’t even have comments! Yet, classes are a weird feature of HTML. Are they visible to the end user? By default, no. But by all practical purposes they are the primary hooks CSS uses to modify how things appear to users.

Using wrapper divs is often a great way to manage layout and spacing and other important design considerations. As discussed above, because there is no Markdown-in-HTML-in-Markdown, any child content of a wrapper div then has to become HTML too, and you lose the benefit of using Markdown at all.

Unfortunately my case is diminished greatly by the lack of constructive suggestions to do this well. Axel Rauschmayer chimed in to offer Pandoc’s format – as a Markdown flavor, I’d wish for something that degrades gracefully to common Markdown viewers, like code fences do. If Gruber had designed this into Markdown from the get-go, whatever the syntax, we would not have this problem or this objection.

This is important for URL accessibility. Here we have a normal markdown header:




tag for an anchor link – you could just compile to:


chrome extension for toggling this on and off!

Of course, offering ID’s for headers would also mean taking a stance on how to slug-case content. How would you slug case this?


This is related to the "no way to specify non-visible things" complaint above, but on a whole-document level instead of a per-element level. Sometimes you want to offer Markdown processors some extra data about how this specific Markdown document should be handled differently than others, or just specify other non-HTML data for use by other toolchains like a blogging engine (eg specify what layout format to use , or what categories the blogpost belongs to, and so on).

Instead of having to specify this data in a separate file, it'd be nice to colocate this metadata alongside the content.

There's a reason this probably wasn't offered by Gruber - it involves another language that isn't Markdown and isn't HTML. I don't know this for a fact but it seems like Jekyll was the first to introduce Front Matter

as the widely accepted Markdown metadata format - and it uses YAML, which predates Markdown, but only by 3 years.

YAML itself has plenty of vocal detractors, so it isn't perfect. But something for Metadata would have been really, really nice.



And in the end, Markdown was successful enough. I am writing this blogpost in Markdown, and since I write every day, that means I write Markdown every day. I also build tools that consume Markdown, and live primarily on the web, and thus I feel the painpoints more intimately than others might.


(Read More )

What do you think?

Leave a Reply

Your email address will not be published.

GIPHY App Key not set. Please check settings

5G mast 'on fire' hours after mayor slams 'bizarre' coronavirus conspiracy theories – Liverpool Echo,

5G mast 'on fire' hours after mayor slams 'bizarre' coronavirus conspiracy theories – Liverpool Echo,

How to win Monopoly in the shortest possible time, Hacker News

How to win Monopoly in the shortest possible time, Hacker News