mdxg

MDXG (Markdown Experience Guidelines) is a specification — not a tool or syntax extension — that defines how apps should present and navigate markdown documents. The problem it addresses is that markdown files, whether 50 lines or 3,000 lines long, are almost always shown as a single flat scrollable page with no structure or navigation aids, even though markdown is the most common document format in software and AI output alike.

The spec works at the presentation layer, meaning it doesn't change your actual markdown files at all — it just defines how apps should display them. The key idea is splitting a document at its H1 and H2 headings into virtual pages, giving readers navigation between those pages, a page outline for subheadings, search across the whole document, syntax highlighting with copy buttons on code blocks, and the ability to toggle between a rendered view and an editable source view. Implementations can surface these features through sidebars, keyboard shortcuts, swipe gestures, or whatever fits their platform.

You would use this specification if you're building a tool that renders markdown — a text editor plugin, a documentation platform, a note-taking app, or an AI interface — and you want to give users a polished, navigable reading experience without reinventing the wheel. The repo includes a reference implementation as a VS Code extension and a shared TypeScript parser library that handles document splitting and heading extraction.