markdown-it

markdown-it is a Markdown parser for JavaScript that fully implements the CommonMark specification while adding practical extensions like GitHub-flavored tables, strikethrough, URL autolinking, and typographic replacements. It compiles Markdown into a token stream rather than a traditional AST, which keeps the core fast and makes every stage of parsing and rendering independently overridable.

Rather than baking in every feature, markdown-it exposes a rule-based architecture with three chained parsers (core, block, inline) that plugins can extend via .use(). This has produced one of the largest Markdown plugin ecosystems in the JS world, covering footnotes, definition lists, emoji, custom containers, and more, while the parser itself stays secure by default — it disables raw HTML and blocks dangerous URL schemes unless you explicitly opt in.

What You Get

• A 100% CommonMark-compliant core parser, verified against the official spec test suite on every change
• Built-in GFM-style extensions: tables, strikethrough, and optional linkify/typographer replacements
• A rule-based Ruler API (.before(), .after(), .push(), .enable(), .disable()) for inserting, replacing, or toggling parse rules without forking
• Three ready-made presets (default, commonmark, zero) as configuration starting points
• Safe-by-default output — raw HTML and dangerous URL schemes (javascript:, vbscript:, file:) are blocked unless explicitly enabled
• One of the largest third-party plugin ecosystems of any JS Markdown parser (footnotes, definition lists, emoji, custom containers, subscript/superscript, and more)

Common Use Cases

• Rendering user- or CMS-authored Markdown to HTML on a server or in a static site generator
• Building a documentation or blogging platform that needs custom Markdown syntax via plugins
• Adding a live Markdown preview/editor to a web app, using renderInline for single-line contexts
• Post-processing rendered links or code blocks (e.g. syntax highlighting, target="_blank", custom embeds) by overriding specific renderer rules

Under The Hood

Architecture — markdown-it compiles Markdown into a flat token stream instead of a nested AST, then hands that stream to a separate Renderer. Parsing runs through three chained rule pipelines defined in lib/parser_core.mjs, lib/parser_block.mjs, and lib/parser_inline.mjs: core rules (lib/rules_core/*, e.g. normalize.mjs, block.mjs, inline.mjs, linkify.mjs, replacements.mjs) drive the top-level sequence, block rules (lib/rules_block/* — heading.mjs, list.mjs, table.mjs, fence.mjs, blockquote.mjs, etc.) turn lines into paired open/close block tokens, and inline rules (lib/rules_inline/* — emphasis.mjs, link.mjs, image.mjs, autolink.mjs, strikethrough.mjs) fill each inline-container token’s children array. Each pipeline gets its own independent state object (state_core.mjs, state_block.mjs, state_inline.mjs), which is what lets rules stay decoupled and individually enable/disable-able. Renderer (lib/renderer.mjs) then walks the token array and dispatches each token to a function keyed by token type in renderer.rules, so consumers can override single token types (e.g. link_open) without touching the parser.

Tech Stack — Pure JavaScript (ESM, .mjs throughout, with a generated dist/index.cjs.js for CJS consumers), zero build step required to run the library itself. Runtime dependencies are narrowly scoped utility packages by the same authors/ecosystem: linkify-it (URL autodetection), mdurl (URL parsing/encoding), entities (HTML entity handling), punycode.js (IDN hostname encoding), uc.micro (Unicode category tables), and argparse (only for the bin/markdown-it.mjs CLI). Dev tooling is eslint with neostandard, c8 for coverage, vite for building the browser bundle, and Node’s built-in node --test runner — no third-party test framework dependency.

Code Quality — Testing is unusually rigorous for a parser library: test/cmspec/commonmark.test.mjs runs the full upstream CommonMark specification conformance suite, test/markdown-it/ covers the public API (markdown-it.test.mjs), the Ruler extension mechanism (ruler.test.mjs), the Token class (token.test.mjs), miscellaneous edge cases (misc.test.mjs), and there’s a dedicated pathological.test.mjs plus support/track-ref-pathological.mjs that specifically hunts for catastrophic-backtracking/ReDoS-style inputs — a strong signal of security-conscious maintenance given the library parses untrusted user input by design. test/build/build.test.mjs verifies the built distributable actually works. Source files use consistent JSDoc-style comments describing each public method’s signature (visible directly in lib/index.mjs and lib/token.mjs), and eslint.config.mjs enforces neostandard style project-wide.

API Design — The primary surface is small and idiomatic: markdownit([preset], [options]) constructs an instance, .render(str) / .renderInline(str) produce output, and .use(plugin, ...opts) chains plugin installation in a fluent style. Extensibility is handled through Ruler.before/after/push (lib/ruler.mjs), letting plugin authors insert or replace individual rules by name in any of the three chains without forking the library, and .enable()/.disable() toggle built-in rules on/off per instance. Three built-in presets (default, commonmark, zero) cover the common configuration starting points. Security defaults (HTML disabled, dangerous URL schemes blocked per docs/safety.md) are opt-out rather than opt-in, which lowers the chance of an integrator accidentally shipping an XSS hole. This rule-based extension model is the reason the package has one of the largest third-party plugin ecosystems (footnotes, definition lists, emoji, containers, etc.) of any JS Markdown parser.