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:
or even:
3. Bird 1. McHale 8. Parish
you 'd get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don't have to.
This laziness is good for, well, the lazy. I know some people love this feature. But we read markdown more than we write it - even as the people writing it! It is a 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:
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:
(div)
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.
John Gruber actually saw this criticism
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.
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:
my-title
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?
#
There are also quibbles about case sensitivity and hyphens vs underscores. But I don't really care - pick one, let me link directly to content !!
Of course, GitHub Flavored Markdown deals with this with GitHub's postprocessing and you can add this feature in widely used Markdown processors. But it would have been nice to be in the spec.
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.
(Conclusion) ()
(Read More )
GIPHY App Key not set. Please check settings