Markdown is a terrible language

Overview

The video is a technical rant/analysis arguing that Markdown (specifically CommonMark) was designed as a minimal, reliable markup format, but modern usage has drifted into something closer to a fragile “language runtime”—especially when people push it toward richer document features, programming-like behaviors, and agent/LLM communication.

Key Technological Arguments & Concepts

Markdown’s original purpose vs. current use

• Original intent: Markdown is praised as a minimal typesetting syntax meant to render to HTML, with:
  • a simple mental model,
  • readable source,
  • easy learning.
• Current critique (feature drift): People extend Markdown beyond that primitive model, creating unclear expectations such as:
  • “Do we want UI?”
  • “Do we want a programming language?”
  • “Do we want a document format?”
• Result: The more extensions/plugins/inlined content are added, the less Markdown behaves like “just transliteration” into HTML.

Feature creep and syntax ambiguity (CommonMark vs. implementations)

• Ambiguity even within CommonMark: The video highlights that multiple syntaxes can exist to express the same formatting.
• Implementation divergence: Non–CommonMark-compliant implementations may accept additional ambiguous/overlapping forms.
• Practical impact: This creates parsing complexity for both:
  • parser authors, and
  • document authors,

because “what you typed” does not uniquely determine how it will be parsed/rendered.

Parsing hardness and security issues

The video argues that the main parsing difficulty isn’t only Markdown rules, but that many Markdown systems must also parse HTML when inline HTML is allowed.

• Expanded attack surface:
  • inline HTML,
  • plugin hooks,
  • shortcodes,
  • execution engines

are said to increase security risk.

• Recurring vulnerability pattern: This is linked to recurring XSS (cross-site scripting) issues across many Markdown implementations.
• Concrete vulnerability class mentioned: ReDoS (regular expression denial of service)
  • e.g., certain Markdown patterns (such as many stars in links) can cause extreme processing time.
• Reported vulnerabilities referenced: The video notes CVEs affecting Markdown parsing.

Context sensitivity via footnotes / reference-style constructs

Markdown is described as not purely context-free in practice because some constructs require global resolution, including:

• Footnotes
• reference-style links

This shifts the “grammar model” toward context-sensitive parsing, where the meaning of tokens can depend on declarations elsewhere in the document.

Rendering is the real problem (Markdown becomes a compiler + dependency graph)

The core argument is that vanilla Markdown could be a near one-to-one mapping into HTML, but modern ecosystems often behave like a build toolchain.

Examples of “compiler-like” behavior:

• Footnotes → additional compilation behavior
• Custom callouts/hooks → dependency graph + transformation stages
• Math → typesetting engines
• Custom styling/CSS → cross-file scoping and CSS injection concerns

So the system becomes “formatting + build tooling,” but without formal constraints.

Attempts to “solve” it with other syntaxes

The video mentions common alternatives and their issues:

• MDX (pushed toward code/HTML-like behavior)
• reStructuredText (described as nicer for read-only scenarios)
• “Plain text” being beautiful but not beginner-friendly
• Async syntax in Markdown being especially “cursed” (execution embedded in markup)

Overall, alternatives are said to still inherit problems and often still lack a proper build system.

Proposed Direction (High-Level)

The “better solution” proposed is not “rewrite everything in HTML,” but to define a saner, purpose-built markup language with:

• no inline HTML
• well-defined shortcodes/functions for transformations
• compile-time hooks (before/during/after compilation)
• clear constraints and a real build system

Otherwise, Markdown continues becoming a Frankenstein tool that fails both at:

• document simplicity, and
• “language-like” guarantees.

Historical Implementation Criticism

The video claims early Markdown implementations (e.g., markdown.pl by John Gruber) had bugs/misfeatures, and that later implementations sometimes replicated those errors.

• A specific historical issue is mentioned:
  • token-hash replacement behavior that contributed to an XSS incident

Reviews / Guides / Tutorials

This is characterized as primarily:

• an engineering/security analysis, and
• a formal-language critique of Markdown.

It’s not positioned as a step-by-step user guide. The only “how-to” element is conceptual: if you want “power,” you end up needing a build/compilation pipeline—and Markdown ecosystems often approximate that poorly.

Sponsor / Product Feature Mentioned

The video includes an ad for RWX, focused on CI workflows:

• Write a YAML CI file
• Use an RWX CLI to trigger runs without committing/pushing code
• It spins up cloud instances while using caching
• It supports agent workflows, enabling faster loops like:
  • “make changes → run CI locally/agent-assisted → commit if it passes”
• Mentions parallelism to reduce iterative CI delays

Main Speakers / Sources (as stated)

• Brock (author of the article being discussed; thanked explicitly)
• John Gruber and Aaron Swartz (credited for creating Markdown)
• Jeff Atwood (referenced via a 2012 article urging Gruber to change/bless standardization attempts)
• Jacob Evans (mentioned as attempting to present Markdown as HTML using overlapping bytes for GitHub profile/homepage)
• John Gruber’s markdown.pl (criticized as a poor early implementation)
• Sponsor: RWX (Run Loops / CLI for CI)