Markdown – or, more accurately, incompatible variants of Markdown – is everywhere, but that doesn’t mean everybody likes it. It’s the lowest common denominator of light markup languages, with a lot of well-documented issues, and Karl Voit decided to write a long and detailed article about the Markdown’s shortcomings.
Just to make sure we’re on the same page here: I do not want to take away awesome workflows that are made possible by using an LML like Markdown. I just want to mention that the very same kind of workflows are possible by using a better designed LML.
Unfortunately, some issues mentioned here do seem very subtle and minor. However, their consequences are not. With LMLs getting more and more popular and gaining wider use in tools, we really should make sure that our LML choice is a really good one. Personal feelings aside.
↫ Karl Voit
Voit clearly has a preference for a specific alternative LML, but that doesn’t mean the points they make in the article are any less valid. The world of Markdown is chaotic, with a seemingly endless number of varieties and dialects, perfectly illustrated by the Markdown Monster. To make matters worse, the Markdown syntax is quite ambiguous, further complicating how you’re supposed to write it, and how tools are supposed to process it. The end result is that documents you write in Markdown today might be difficult to process decades from now, which isn’t exactly conducive to its intended function.
Voit mentions more issues, but this is the main gist.
There’s one major issue – at least for me – that Voit doesn’t go into, and that’s a problem I have with any of these simple markup languages I’ve tried: their syntaxes rely on some of the most annoying and cumbersome characters to type. There’s a lot of weird keyboard clawing you need to do to enter the characters required by the syntax, and it just makes for an uncomfortable typing experience for me. I wish someone would design one of these syntaxes with typability in mind, making sure to only use characters that are easy to type. While this probably imposes some pretty hefty restrictions during the design of such a syntax, I think it can make for a much more elegant typing experience.
As a result, I do not use Markdown or any of its alternatives.
Never used it because I can’t stand the name. Markdown and the propsed replacement orgdown both have names that are quite depressing to me. I prefer to write everything in a plain text file with no attempt at formatting apart from caps, spaces, tabs, and paragraphs.
I love Markdown but have noticed that there are different flavors or custom flavors in certain apps. That is kind of annoying, because I am not always sure what the differences are.
With that said, I think Markdown is great for its intended purpose – which is to help writers and bloggers do some basic stylizing that can get transferred over to different platforms in an agnostic and simple way. I basically just use bold, italics, 3 headers, block quotes, code blocks, horizontal line, and occasional links and images. But even the last two are kind of lame to do with Markdown, so I much prefer to do them in the final doc whether that is Google Doc or Craft or WordPress or whatever.
I see people doing tables and stuff with them, and that is just wild!!!! Like if you need tables, go to a real word processor (aka Pages). 🙂
rustdoc turns on pulldown-cmark’s support for rendering GitHub-Flavoured Markdown tables in otherwise CommonMark-compliant Markdown specifically so you can embed tables in your API documentation without having to split said API documentation out of your source code into separate files.
Some functions are just much easier to explain with a table.
I love Markdown. It liberated from using Word for technical documents. It easy to write and easy to read when not even rendered. It took the place of stupid XML tags in modern languages’ doc comments. I love the name, keeps the mark-up down!
If you need stuff where MD ambiguity is a problam, you should probably use something else instead.
drstorm,
Yes, markdown is a very good tool to write technical docs without needing LaTeX or other typesetting software. It can also be read by human eyes (to a point). Even tables can be made visually useful with some effort.
RichText back in the day was supposed to be this, but it was too convoluted:
vs
For the custom renderer I’ve been dogfooding, I went a step further and implemented support for custom language strings for fenced code blocks which don’t fall through to the default syntax highlighter and instead render svgbob or GraphViz diagrams to inline SVG.
Great for something that renders to a nice diagram in the output while still being reasonably readable in “plaintext”.
(I want to support more use-cases, but those were the first two I found native Rust renderers for that I could statically link into my renderer or build into self-contained
.wasmplugins.)ssokolow,
This is actually quite nice. Thanks for introducing me to svgbob.
> I wish someone would design one of these syntaxes with typability in mind, making sure to only use characters that are easy to type. While this probably imposes some pretty hefty restrictions during the design of such a syntax, I think it can make for a much more elegant typing experience.
The problem is that keyboards are designed primarily around human languages, so the keys that are more easily reached also happen to be the ones that are more likely to conflict with your average human’s text, which would make for a distinctly *less* elegant typing experience.
I love markdown because of one of it’s base principles:
A well written markdown document is also a well-written plain text document, without any fanfare (markup for the sake of markup).
The fact that (a markdown flavour) is available in most system is sugar on top.I like commonmark even more as it fixes some of the biggest papercuts and makes it behave a bit more deterministic, but it also muddies the water with being yet another standard.
Markdown is fine for stuff like README, building instructions, or some random post on the internet. For documentation it’s horrible, and I much prefer WikiText, although it seems that only MediaWiki supports it.
Examples? My opinion is the opposite… though, to be fair, I do tend to work in dialects of Markdown with extensions that pull it closer to “reStructuredText with less ugly” and I’m used to tolerating reStructureText in my Python projects.
…because it’s their proprietary syntax, same as how TiddlyWiki, MoinMoin, DokuWiki, PmWiki, TWiki, and every other wiki package has its own syntax.
(Though it wouldn’t surprise me to learn that wikis now exist which use some flavour of Markdown.)
Regarding typeability, i assume you use a Dutch or Norwegian keyboard, where they are indeed annoying to type. It is, maybe not very surprisingly, much easier to type on an American keyboard. I constantly switch layout between Danish and US depending on if i am coding or doing something else.
I also like Markdown, and now, with AI, a lot of personal notes are using Markdown. When Windows 11 dropped WordPad (which had richtext support), I thought they would introduce a new simple editor that uses Markdown.
I like Markdown for anything simple to get a bit of formatting and it’s more than enough for 95% of the cases… for anything more complex asciidoc is there for you.
OTOH some argue to use reStructured text – if you think that Markdown is terrible then try using this pile of crap that rST is 😀
Makes sense. It’s designed to map 1-to-1 to DocBook XML and I do love how it’s had O’Reilly-inspired “admonition” syntax for 20 years.
However, I’m using Markdown for that role for now, because the most likely-looking crate to be easily swapped out for pulldown-cmark in my renderer says “The project is in its infancy as of July 2025 and in no way ready to use.” in its README and I’d rather just write markdown than babysit another project without Rust’s compile-time guarantees, Cargo builds, and Go-esque self-contained binaries.
(Thankfully, pulldown-cmark’s support for admonitions from GitHub-Flavoured Markdown as a CommonMark syntax extension is perfectly suitable for me now that I’ve written an iterator adapter to bodge on support for recognizing admonition syntax when there’s a blank line between the admonition header and the body so Prettier doesn’t re-word-wrap it into just any blockquote.)
EMACS is the solution to all the world’s problems, according to TFA. I have been refusing to learn it for decades, not sure I’d live long enough now. I took much the same attitude towards MPW: I can get along without all the things they can do, that have to be constantly looked up because you haven’t needed to recently.
Basic markdown has close to a zero learning curve; for more than basic text, use a real word processor.
I’ve seen people fighting with misbehaviour due to invisible tags in WYSIWYG editors so many times, be they MS Word, StarOffice/OpenOffice.org/LibreOffice, various HTML editors, or whatever else.
For me, seeing the raw syntax of the authoritative copy is non-negotiable and Markdown massively reduced the number of raw HTML tags I had to type. (I still type some, because Markdown is designed to delegate the more complex stuff to inline HTML tags like <abbr>.)
Hell, when I wanted a fancy Christmas/Birthday wishlist to satisfy my brother’s request to try to bring back that sense of excitement from childhood, I reached for pulldown-cmark and wrote my own CommonMark-ingesting rendering harness in Rust.
That said, it would be nice if a WYSIWYM (What You See Is What You Mean) GUI like LyX existed that wasn’t so tied to LaTeX.
It’s a shame WYMeditor (demos) had its last update in 2014 and it’s the only non-LyX WYSIWYM editor I know of.
Have you looked at typst?
Every time I see an article like this it boils down to: the “problem” with Markdown is that it doesn’t work well for use cases it wasn’t designed for, like a screwdriver that someone’s trying to use as a hammer.
Markdown is good for writing text-based documents that will have a consistent presentation, and since it’s built on conventions from text-only email, newsgroups, forums, and messaging apps, it’s usually easily human-readable in its raw form.
Until you try to use it for something it wasn’t designed for, like tables, diagrams, advanced math formulas, or image-heavy documents. You’re right! It’s terrible for those! Use another tool for those use cases!
One just has to browse Reddit to see why Markdown is bad as an input syntax: it’s full of posts that aren’t rendered as intended because the writer forgot to leave an empty line before a list (why is it needed?), or assumed that you can manually enumerate a numbered list (you can’t, it will start from 1. and go on from there, no matter what numbers you write), or that you can break a list entry into paragraphs (nope), or that a newline means a newline (aaarghh!!! why not???).
For my personal notes, I played with Markdown a bit, and then with Asciidoc (probably better), but I generally use either TiddlyWiki for hyperlinked stuff, spreadsheets whenever I can organise the info into a table, or just plain text files with indentation for hierarchical structure (tabs for indentation, spaces for alignment, I’m willing to die on this hill).
I used org-mode for a while, and it’s cool and powerful, but eventually I decided that I hate Emacs, and despite what the author says, using “Orgdown” when nothing *actually* supports it is pointless.
I also used LyX to write my thesis, and it’s been a rather smooth experience, but I haven’t had any reason to use it ever again.
On a related note, what’s the syntax here in the comments? I couldn’t find how to properly format quotes.
CommonMark agrees:
The issue is that Reddit, in a fit of brilliance, parses the same post source as either old-style Reddit-dialect Markdown (old.reddit.com) or their new subset of CommonMark (www.reddit.com) depending on which version of Reddit you use, rather than either storing a flag in the database for each post or just upgrading Old Reddit to CommonMark parsing.
Again, that’s something people agreed was a mistake and CommonMark fixes it as long as the parser plumbs the information through to the HTML renderer:
I believe the reason subsequent list item numbers are discarded is so you can add, remove, and reorder without relying on a code formatter to fix up the numbering. (In fact, Prettier supports “Everything starts with the same number… usually 1” style of Markdown lists.)
Every dialect of Markdown I remember trying it on supports that… you just have to get the indent level correct.
Here’s what CommonMark has to say about it:
Markdown is designed to also be readable as hard word-wrapped plaintext, so it unwraps your lines to let the browser soft-wrap them. (It’s consistent with Markdown being designed to be something you can edit in any old vt100 text editor and have look good good in a modern web browser when rendered.)
If you want a <br /> tag to be emitted, you stick a backslash at the end of the line to escape the newline character, same as with any other character that Markdown applies special handling to when you want it to be rendered literally.
Markdown was never meant to be used for elaborate formatting, it was always meant to be a tiny bit of ignorable formatting “spice” on plain text, so ambiguities in handling shouldn’t matter because you shouldn’t be making heavy enough use of Markdown for them to matter in the first place.
But of course, this doesn’t prevent people from making elaborately-formatted documents in Markdown (that are a pain to read in plain text) and then complain when they run into parser differences. Oh well…
A late comment but I would like to put in a good word for BBCode as the “approximately right balance”. XML-based syntax becomes problematic without using an XML-aware editor to handle the character encoding, because too many regular English characters are reserved. Attempts to make a super light syntax like Markdown are very application-specific, so everyone struggles to remember “which flavor”. Working in HTML can be lower-level than needed – it mixes together a lot of the layers of the web stack, and it’s challenging to secure that.
BBCode gets these things right because it’s nested-bracket syntax, made for authorship in plain text, made to be parsed and compiled before rendering, and it can be extended in a regular and fallback-friendly way. It’s not very pretty, or academically rigorous, nor is it built to reference a particular standard or implementation, but as a syntax, it checks a lot of boxes and it’s already been implemented a few times, so no wheels need be reinvented to start using it.