pulldown-cmark

pulldown-cmark is a pull-based CommonMark parser for Rust that turns Markdown source into an iterator of events rather than a fully materialized document tree. That design keeps memory allocation to a minimum, since most text is emitted as zero-copy slices of the original source, and it lets callers transform or filter the parse stream with ordinary iterator combinators like map and filter. It targets 100% compliance with the CommonMark spec while optionally supporting GitHub-flavored extensions such as tables, task lists, footnotes, and strikethrough.

What You Get

• A pull-style Parser implementing Rust’s Iterator trait over Event values for start/end tags, text, breaks, and inline content
• A built-in HTML renderer (html::push_html) for converting the event stream directly into an HTML string buffer
• Optional CommonMark extensions: tables, task lists, footnotes, strikethrough, smart punctuation, and ==highlight== marks
• Source-map support via into_offset_iter(), yielding (Event, Range) pairs that map each event back to its byte offset in the source
• A no_std-compatible build (via --no-default-features plus hashbrown) for use in constrained environments
• A bundled CLI binary for quick Markdown-to-HTML rendering from the command line

Common Use Cases

• Rendering Markdown documentation, README files, or CMS content to HTML at build time or request time
• Building custom Markdown transformations (e.g. soft-break-to-hard-break conversion, link rewriting) by mapping over the event iterator
• Powering static site generators and documentation tools (it is the parser behind mdBook and other Rust doc tooling) where source-map fidelity and performance matter
• Extracting structured data from Markdown (headings, links, code blocks) by consuming the event stream without building a full AST

Under The Hood

Architecture — The parser runs a first pass (firstpass.rs) that scans the source for block-level structure and builds a tree of block spans (tree.rs), followed by an inline pass (parse.rs) that resolves emphasis, links, and other span-level constructs against that tree; lib.rs exposes the resulting Parser as a Rust Iterator<Item = Event>, and html.rs is a separate consumer that walks the same event stream to emit HTML, keeping parsing and rendering strictly decoupled. Tech Stack — Pure Rust (98.5% of the codebase) with zero required dependencies for the core parser; entities.rs and puncttable.rs are large generated lookup tables for HTML entity decoding and Unicode punctuation classification, and an optional simd feature enables SIMD-accelerated scanning on x86-64. Code Quality — The workspace includes a dedicated tests/ directory plus specs/ containing the CommonMark spec test suite, a fuzz/ and dos-fuzzer/ crate for fuzz-testing parser robustness (guarding against pathological/adversarial input), and CI-run bench/ benchmarks; the crate compiles under #![no_std]-friendly configurations, evidence of disciplined dependency and API-surface hygiene. API Design — The Iterator-based Event API is idiomatic Rust, requires only 3-4 lines to go from Markdown string to HTML output, and cleanly separates parsing from rendering so consumers can filter, map, or collect the event stream before it ever touches HTML — a deliberate improvement over push-parser designs common in other Markdown libraries.