markdown-it

markdown-it is a Rust port of the popular markdown-it.js library, offering 100% CommonMark compatibility along with a real abstract syntax tree and complete source-map support. Unlike faster single-purpose parsers, its defining strength is extensibility: the entire CommonMark grammar is itself implemented as a plugin, so you can define custom inline and block syntax of arbitrary complexity — @mentions, :emoji:, custom HTML classes, or even other markup languages entirely.

The library parses input into an inspectable AST, which you can walk, transform, and render to HTML. This makes it a strong fit for applications that need to go beyond stock Markdown, where control over tokens, node types, and rendering matters more than raw throughput.

What You Get

• A 100% CommonMark-compliant parser with an inspectable abstract syntax tree
• Full source-map support down to inline tokens, not just block-level tags
• A plugin API powerful enough to express the CommonMark grammar itself
• Optional built-in extras such as linkify autolinking and syntect-based highlighting
• A WASM-ready core with a browsable in-browser demo

Common Use Cases

• Building custom Markdown flavors with bespoke inline or block syntax
• Rendering user-authored Markdown to HTML in web and desktop apps
• Parsing Markdown into an AST for analysis, linting, or transformation

Under The Hood

Architecture - The core (src/lib.rs) defines a MarkdownIt parser instance to which plugins register rules; parsing runs in block then inline phases, producing a tree of Node values (src/parser) each carrying a typed NodeValue and source-map span. Rendering walks that tree via a Renderer trait, so the AST is the stable seam between parsing and output. The bundled CommonMark grammar lives under src/plugins/cmark, deliberately implemented against the same public plugin API third-party extensions use.

Tech Stack - Pure Rust (edition 2021), depending on regex, once_cell, downcast-rs, and derive_more among others; optional linkify and syntect features add autolinking and highlighting. Version ranges are pinned with tested lower bounds, and the crate compiles to WASM for the browser demo under demo/.

Code Quality - The tests/ directory is substantial, covering the CommonMark spec, typographer, smartquotes, source maps, and pathological inputs against fixtures, indicating strong regression coverage. Node types are strongly typed via a downcast-based trait system, and the codebase favors explicit small modules per rule.

API Design - Getting started takes only a few lines: construct a parser, add plugin bundles, call parse then render. The extension API is more involved — defining custom node types and rules requires understanding the trait model — but the examples/ folder walks through it incrementally, keeping the common path ergonomic while exposing full power for advanced use.