Markdown’s Simplicity and Complexity: Syntax, Extensions and Security

I have advocated for Markdown for years. I once kept my résumé on GitHub as Markdown and even avoided some applications that would not accept it. Its appeal was a simple, readable source that could become a nicely formatted document without elaborate tooling.

I am grateful to John Gruber and Aaron Swartz for creating Markdown. After struggling with LaTeX in college, I found a format that clicked and became my default for writing. That history is why an article asking why we still use Markdown caught my attention.

Markdown’s scope has expanded beyond simple documents. We embed other formats, add extensions and increasingly use Markdown to communicate with language models and agents. I want to question where the original format works well and where our newer demands create friction.

The article I am reading is “Why the heck are we still using Markdown?” by Brock: https://bgslabs.org/blog/why-are-we-using-markdown/. The author focuses primarily on CommonMark and argues that a format intended to be simple has accumulated difficult syntax and expectations. I agree with much of the frustration, even though I still use it every day.

The good part is real: basic Markdown is approachable, readable in plain text and convenient for headings, emphasis and links. CommonMark gives implementations a detailed shared specification. A casual author can get useful output quickly without learning the full set of parsing rules.

The trouble begins when multiple spellings produce the same result. The article shows one heading written with a hash and another using an underline; it also switches between asterisks and underscores for emphasis. These choices can be convenient for writers but create more cases for tools to handle.

Nested emphasis can become hard to read even before implementing a parser. In T3 Chat we have encountered many odd rendering cases, especially with generated content. A simple-looking format can therefore impose substantial complexity on the software that must accept all of its valid forms.

The article points to a regular-expression denial-of-service vulnerability in markdown-it. This is a bug in particular affected versions and code paths, not evidence that every Markdown parser is vulnerable. The advisory identifies versions 13.0.0 through before 14.1.1 and a fix in 14.1.1: https://github.com/advisories/GHSA-38c4-r59v-3vqw.

The author compares inline HTML in Markdown to adding a powerful escape hatch. It lets a writer use elements and attributes the basic syntax cannot express, but now the rendering pipeline must decide how to handle two different syntaxes and their interactions. That flexibility has a cost.

I have felt this problem personally. A friend tried to use the same bytes as both a GitHub profile Markdown file and an HTML home page; making the two rendering environments agree was painful. The fact that some HTML can appear in Markdown does not mean every renderer treats the combined document identically.

Writers often want more than headings and paragraphs: embedded media, diagrams, mathematics, footnotes, citations, styling or interactive components. Each added capability introduces choices about syntax, dependencies and trust. A tool intended as a lightweight text format starts to resemble a document-processing system.

I looked at my own blog and quickly found an iframe and an HTML image inside a Markdown link. The point is not that those particular snippets are inherently unsafe; it is that real publishing requirements push us beyond the simplest Markdown examples and into mixed-format workflows.

Allowing raw HTML, plugins or executable extensions changes the security model. When content is untrusted, the application needs appropriate sanitization and boundaries; a parser alone is not a complete security policy. Different implementations and configurations carry different risks.

Markdown borrowed conventions from plain-text email and online discussions. That history left several ways to express similar structures: heading styles, list markers, horizontal rules and emphasis delimiters. Familiarity makes them easy to use, but overlaps and variations make edge cases harder to reason about.

Numbered lists are another example: authors can use repeated markers and rely on the renderer to produce the displayed sequence. That is convenient when reordering items, but the text a person sees in the file and the rendered output do not always match one-to-one.

The article shows a reference whose interpretation depends on whether a matching definition appears elsewhere in the document. CommonMark supports reference links; footnotes are an extension rather than a core CommonMark feature. A renderer may need a document-wide reference table or multiple passes to resolve such links.

The author describes that dependency using formal-language terminology and argues that Markdown is more complicated than a simple local substitution. The practical observation is sound: later definitions can affect earlier references. The formal classification is the author’s argument, not something established merely by the example shown.

Add footnotes, custom callouts, mathematics and styles, and the processing pipeline grows further. A knowledge-management system may need plugins and typesetting libraries as well as a way to scope styles. The format choice should account for the whole pipeline, not just the characters an author types.

I like one different use of Markdown syntax in Notion: typing a hash and a space can turn a block into a heading. There, familiar syntax acts like a shortcut in an editor. That is a distinct use from storing and rendering an entire document as Markdown, and the export can have its own limitations.

The author considers plain text, reStructuredText and MDX, but finds tradeoffs in each. The proposed alternative is a clearly specified markup format with a build system, explicit shortcodes and controlled hooks instead of unrestricted inline HTML. That is a design proposal, not an already demonstrated universal replacement.

A build system and hooks can make extension points explicit, but they also introduce their own complexity and security decisions. The key question is which features a document actually needs and which code is trusted to run during processing. A cleaner grammar alone does not make arbitrary extensions safe.

The article also ventures into formal language theory and definitions of programming languages. Those distinctions depend on the precise language and computational model being discussed; an entertaining argument about Markdown should not be taken as proof that Markdown itself is Turing-complete.

There have been complaints about Markdown’s ambiguities and implementation bugs for a long time, including calls for a clearer standard. CommonMark is one response to that history. Standardizing behavior can improve consistency while still leaving open the question of whether the chosen behavior is pleasant or appropriate for a particular application.

The article made me appreciate how much complexity I have accepted in a format I use every day. I am not proposing that everyone rewrite their documents immediately. I want us to recognize the tradeoff: Markdown is pleasant for simple text, while extensions, mixed HTML and rendering requirements can make the surrounding system much harder.

I am tempted to invent a new markup language, but that temptation is not a solution by itself. First decide what you need to express, how documents are processed and what security boundaries matter. Then choose or design tooling for those requirements.