mdast-util-from-markdown

mdast-util-from-markdown is the low-level utility that converts markdown into an mdast syntax tree, used when you need to work with the parsed tree directly instead of going straight to HTML. It delegates tokenization to micromark’s CommonMark-compliant parser, then compiles the resulting token events into mdast nodes (headings, lists, links, code, emphasis, and more) via a stack-based compiler with dedicated enter/exit handlers for every token type.

Its extension system is what makes it foundational to the wider syntax-tree ecosystem: passing micromark extensions adds new markdown syntax (GFM, MDX, math, directives, frontmatter), while mdastExtensions register the enter/exit handlers and post-parse transforms needed to turn those new tokens into mdast nodes. Packages like mdast-util-gfm, mdast-util-mdx, and remark-parse all build on this exact mechanism rather than reimplementing markdown parsing themselves.

What You Get

• A single fromMarkdown(value, encoding?, options?) function that returns a complete mdast Root node
• Support for micromark extensions (syntax) and mdastExtensions (tree-building) so ecosystem plugins like GFM, MDX, and frontmatter can be layered in without forking the parser
• Exported TypeScript types (CompileContext, CompileData, Extension, Handle, Options, Token, Transform) for building your own extensions
• A CommonMark fixture-backed test suite enforcing 100% line/branch/function coverage, run against both development and production build conditions

Common Use Cases

• Parsing markdown files into an inspectable, transformable AST instead of straight to HTML
• Building a custom remark/unified plugin that needs to add or rewrite mdast nodes
• Powering MDX, frontmatter, GFM, or math syntax extensions across the syntax-tree ecosystem
• Writing markdown linters or static-analysis tools that need positional/token-level detail

Under The Hood

Architecture

The public fromMarkdown(value, encoding, options) in dev/lib/index.js is a thin composition: it feeds value through micromark’s preprocess(), parse().document().write(), and postprocess() to get a token event stream, then hands that stream to an internal compiler(options). The compiler builds a default config object mapping every micromark token name (atxHeading, codeFenced, link, listItem, etc.) to enter/exit handler functions produced by opener()/closer() factories, merges in any user-supplied mdastExtensions via a configure() step, then walks the events maintaining a node stack, a tokenStack (to detect unclosed tokens and raise OnEnterError/OnExitError), and a buffer()/resume() pair that captures raw text for constructs like link destinations before they are finalized into node fields. This gives the whole ecosystem one pluggable seam — new syntax registers handlers here instead of forking the compiler.

Tech Stack

The package is plain, dependency-light JavaScript (ESM only, "type": "module") with no build step for source — only type declarations are emitted via tsc --build with checkJs/declaration/emitDeclarationOnly, so the codebase is fully typed through JSDoc alone. Runtime dependencies are all narrowly scoped micromark/unist/mdast utilities (micromark, micromark-util-decode-string, micromark-util-normalize-identifier, mdast-util-to-string, unist-util-stringify-position) plus devlop for dev-only assertions and decode-named-character-reference for entity decoding. The package exports map exposes a development condition (dev/index.js) alongside the production index.js, letting consumers opt into extra runtime assertions during testing.

Code Quality

A single 1200+ line test/index.js runs the full CommonMark fixture set (test/fixtures/*.md paired with *.json) plus targeted extension and error-path tests, executed once under the development condition and once under production. CI (test-coverage) enforces 100% line, branch, and function coverage via Node’s built-in test runner and coverage flags, and the whole repo is linted with xo (ESLint preset) with Prettier-compatible formatting and a type-coverage check requiring 100% typed code. No test files were skipped or found missing — this is one of the most rigorously tested packages in the unified ecosystem.

What Makes It Unique

Rather than parsing markdown directly into HTML or a bespoke tree shape, this package’s entire value is the clean separation between tokenizing (delegated to micromark) and compiling tokens into a standard, spec-defined tree (mdast). The extensions/mdastExtensions/transforms seams are deliberately narrow and composable, which is why a dozen-plus sibling packages (GFM, MDX, math, directives, frontmatter) can each add markdown syntax independently without touching this package’s internals — a plugin architecture pattern other markdown parsers in the ecosystem have converged on rather than reinvented.