Markdown to mdast AST Parser

2.0.3 · active · verified Sun Apr 19

mdast-util-from-markdown is a foundational utility in the syntax-tree ecosystem, designed to parse Markdown input into an mdast (Markdown Abstract Syntax Tree) syntax tree. It leverages the micromark tokenizer internally and transforms its output into a tree structure. The current stable version is 2.0.3, with frequent patch and minor releases, while major versions like 2.0.0 introduce significant breaking changes such as the shift to ESM-only and a minimum Node.js 16 requirement. This package provides a lower-level API for direct AST manipulation, making it suitable for developers who need fine-grained control over the parsing process or wish to integrate custom syntax extensions like GFM, MDX, Math, or Frontmatter. It is distinct from micromark (which focuses on direct HTML output) and remark-parse (which offers a higher-level, more abstracted content processing experience within the remark ecosystem).

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use CommonJS `require()` in an environment that expects ES Modules.

fix Update your import statements to use `import { fromMarkdown } from 'mdast-util-from-markdown'` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
```
TypeError: Expected Uint8Array, got Buffer
```
cause Passing a Node.js `Buffer` object to `fromMarkdown` for the `value` or `encoding` argument after upgrading to v2.x, which expects `Uint8Array`.

fix Convert your `Buffer` instances to `Uint8Array` before passing them. Example: `fromMarkdown(new Uint8Array(myBuffer))`.
```
Error: Cannot find package 'mdast-util-from-markdown' imported from ...
```
cause Using an outdated Node.js version (prior to 16) with `mdast-util-from-markdown` v2.x, which is ESM-only and requires Node.js 16+.

fix Upgrade your Node.js version to 16 or newer. Also, verify your project's `package.json` correctly specifies `"type": "module"` if you're using explicit ESM in your files.
```
TypeError: fromMarkdown is not a function
```
cause Incorrectly attempting to use a default import for `fromMarkdown`, or a typo in the named import.

fix Ensure you are using a named import: `import { fromMarkdown } from 'mdast-util-from-markdown'`. The package has no default export.

Warnings

breaking Version 2.0.0 of `mdast-util-from-markdown` requires Node.js version 16 or higher. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 16 or newer. Use nvm or your preferred Node.js version manager.
breaking The package became ESM-only (ECMAScript Modules) in version 2.0.0. CommonJS `require()` statements are no longer supported for direct imports.
Fix: Migrate your codebase to use ES module `import` syntax. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions. For mixed CJS/ESM projects, consider dynamic `import()`.
breaking Version 2.0.0 updated its internal `micromark` dependency to v4, which changed how buffers are handled. Input values or encodings that previously accepted Node.js `Buffer` objects now expect `Uint8Array`s.
Fix: If you are passing raw buffers, ensure they are converted to `Uint8Array` instances before passing them to `fromMarkdown`. For example, `new Uint8Array(myBuffer)`.
breaking The internal API for creating custom extensions changed significantly in v2.0.0, specifically replacing getter/setters for some properties with direct assignments.
Fix: If you have custom markdown extensions that interact deeply with `mdast-util-from-markdown`'s internals, you will need to update them according to the `micromark@4` and `mdast-util-from-markdown@2` migration guides. Review `Extension` and `CompileContext` types for changes.
gotcha This utility is for building an mdast syntax tree. If your goal is simply to convert Markdown to HTML, `micromark` is a more direct choice. If you want a higher-level content processing pipeline, consider the `remark` ecosystem and `remark-parse`.
Fix: Choose the right tool for the job: `micromark` for direct HTML, `remark` for plugin-based content transformation, `mdast-util-from-markdown` for direct AST manipulation.

Install

npm install mdast-util-from-markdown npm
yarn add mdast-util-from-markdown yarn
pnpm add mdast-util-from-markdown pnpm

Imports

fromMarkdown
wrong:
```
const fromMarkdown = require('mdast-util-from-markdown')
```
correct:
```
import { fromMarkdown } from 'mdast-util-from-markdown'
```
mdast-util-from-markdown has been ESM-only since v2.0.0, requiring Node.js 16+. CommonJS `require` is not supported for direct imports.
Extension
wrong:
```
import { Extension } from 'mdast-util-from-markdown'
```
correct:
```
import type { Extension } from 'mdast-util-from-markdown'
```
This symbol represents a TypeScript type definition for extending Markdown parsing, not a runtime value. It should be imported as a type.
Options
wrong:
```
import { Options } from 'mdast-util-from-markdown'
```
correct:
```
import type { Options } from 'mdast-util-from-markdown'
```
This symbol represents a TypeScript type definition for the parser configuration, not a runtime value. It should be imported as a type.

Quickstart

This quickstart demonstrates how to asynchronously read a Markdown file and parse its content into an mdast syntax tree using the `fromMarkdown` utility.

import fs from 'node:fs/promises'
import {fromMarkdown} from 'mdast-util-from-markdown'

async function parseExample() {
  // Assume 'example.md' contains '## Hello, *World*!'
  const doc = await fs.readFile('example.md', 'utf8')
  const tree = fromMarkdown(doc)

  console.log(JSON.stringify(tree, null, 2))
  // Expected output:
  // {
  //   "type": "root",
  //   "children": [
  //     {
  //       "type": "heading",
  //       "depth": 2,
  //       "children": [
  //         { "type": "text", "value": "Hello, " },
  //         { "type": "emphasis", "children": [{ "type": "text", "value": "World" }] },
  //         { "type": "text", "value": "!" }
  //       ]
  //     }
  //   ]
  // }
}

parseExample().catch(console.error)

view raw JSON →