micromark

micromark is a markdown parser built to be small, fast, and fully compliant with the CommonMark spec, while also supporting GitHub Flavored Markdown, MDX, directives, frontmatter, and math as opt-in extensions. It parses markdown into a concrete token stream with positional information, then compiles that into HTML (or lets consumers plug in their own compiler), and is designed from the ground up to be safe against malicious input by default rather than requiring separate sanitization.

The project is a monorepo of ~20 packages under the micromark npm scope — the core micromark package plus factory and utility packages (micromark-factory-space, micromark-util-character, micromark-util-symbol, etc.) that its extensions and the wider ecosystem (including remark and mdast-util-from-markdown) depend on directly. It is maintained by Titus Wormer (wooorm) as the parsing engine underlying the unified/remark/rehype content-processing ecosystem.

What You Get

• A 100% CommonMark-compliant parser with 100% GFM (tables, strikethrough, task lists, autolinks) support as an opt-in extension
• MDX, directive, frontmatter, and math syntax extensions that plug into the same core tokenizer
• Safe-by-default HTML output, resisting script injection and malformed input without requiring a separate sanitizer
• A concrete token stream with full positional (line/column/offset) information, suitable for building custom syntax trees
• A documented extension API (SyntaxExtension/HtmlExtension) for adding new markdown constructs
• A companion micromark-build toolchain and shared micromark-util-*/micromark-factory-* packages reused across the ecosystem

Common Use Cases

• Serving as the low-level parser underneath higher-level tools like remark, mdast-util-from-markdown, and static site generators that need markdown-to-HTML or markdown-to-AST conversion
• Rendering user-generated markdown (comments, README previews, chat messages) safely without a separate XSS-sanitization pass
• Building custom markdown dialects or editor tooling that needs positional token information for syntax highlighting or linting

Under The Hood

Architecture: micromark compiles markdown in four conceptual stages, described in its own README: preprocess (normalizing line endings and tabs), parse (a state-machine tokenizer producing events with syntax extensions plugged in), postprocess (resolving and subtokenizing constructs like emphasis that need lookahead), and compile (turning the event stream into HTML or another target via an HtmlExtension). The repo is a Yarn/npm workspaces monorepo (packages/) with the core micromark package depending on sibling packages (micromark-core-commonmark for CommonMark constructs, micromark-factory-* for reusable parsing routines, micromark-util-* for shared helpers like character classification and URI sanitization) rather than inlining that logic.

Tech Stack: Pure JavaScript (ESM-only, type: module), authored with JSDoc-based type annotations checked by TypeScript rather than being written in .ts directly, using Rollup for bundling and a custom micromark-build script. No runtime dependencies outside its own sibling packages plus small utilities (debug, decode-named-character-reference, devlop).

Code Quality: The README advertises roughly 2,000 tests with 100% coverage and fuzz testing, which is unusually rigorous for a markdown parser — a category where edge-case handling (nested emphasis, malformed HTML, unicode) is where most bugs live. Code style is enforced via xo (an ESLint preset) with Prettier. Recent commit activity has slowed relative to the project’s peak (health score flags low recent activity), which is typical for a spec-compliant parser that has reached feature completeness rather than a sign of abandonment.

API Design: The core micromark() function takes a markdown string and options (extensions, htmlExtensions) and returns an HTML string; a separate /stream export supports streaming input. Extensions follow a documented, consistent shape (SyntaxExtension for tokenizing new constructs, HtmlExtension for compiling them), which is what lets GFM, MDX, math, and frontmatter all plug into the same core without forking it. This extension-first design is the main reason downstream projects like remark build directly on micromark instead of writing their own parser.