mdast-util-from-markdown

mdast-util-from-markdown is a utility that converts markdown input into an mdast (Markdown Abstract Syntax Tree) using micromark as the underlying parser.

When to use this:

• Use this if you want to handle syntax trees manually.

When NOT to use this:

• If you just want to turn markdown into HTML, use micromark instead.
• If you want an easier time processing content via a high-level ecosystem, use remark instead.

This package is a low-level building block used by remark-parse to abstract away the tokenization process.

This package is ESM only. Use the following commands depending on your environment:

Node.js (version 16+):

npm install mdast-util-from-markdown

Deno (via esm.sh):

import {fromMarkdown} from 'https://esm.sh/mdast-util-from-markdown@2'

Browsers (via esm.sh):

<script type="module">
  import {fromMarkdown} from 'https://esm.sh/mdast-util-from-markdown@2?bundle'
</script>

The library uses an extension system to modify the parsing behavior. Extensions are applied to a configuration object via the internal configure and extension logic.

An extension object can provide the following keys to influence the parser:

• canContainEols: An array of values that are pushed into the configuration's canContainEols list.
• transforms: An array of transformation functions that are pushed into the configuration's transforms list.
• enter: An object containing handlers for entering specific node types. These are merged into the configuration's enter handlers using Object.assign.
• exit: An object containing handlers for exiting specific node types. These are merged into the configuration's exit handlers using Object.assign.

Extensions can be passed as a single object or as an array of extensions (which can be nested arrays).

The parser includes a default error handler (defaultOnError) that triggers when there is a mismatch in the token stack (e.g., trying to close a node while a different node is still open).

If an error occurs, it throws an Error with a descriptive message containing:

1. The type of the node that was supposed to be closed.
2. The position (line, column, offset) of the unclosed node.
3. The type and position of the token that is currently open and causing the conflict.

The fromMarkdown function converts markdown input (string or Uint8Array) into an mdast syntax tree. This is useful when you want to handle syntax trees manually rather than just converting markdown to HTML.

Example usage:

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

const doc = await fs.readFile('example.md')
const tree = fromMarkdown(doc)

console.log(tree)

The primary API for turning markdown into a syntax tree.

Parameters:

• value (Value): The markdown content to parse (either a string or Uint8Array).
• encoding (Encoding, optional): The character encoding to use if value is a Uint8Array. Defaults to 'utf8'.
• options (Options, optional): Configuration object.

Returns: An mdast Root node.

Overloads:

• (value: Value, encoding: Encoding, options?: Options) => Root
• (value: Value, options?: Options) => Root

When building extensions that require tracking additional data during the compilation process, you should extend the CompileData interface using TypeScript module augmentation.

declare module 'mdast-util-from-markdown' {
  interface CompileData {
    // Register a new field.
    mathFlowInside?: boolean | undefined
  }
}

The Options object allows you to extend the parser's behavior.

Properties:

• extensions (Array<MicromarkExtension>, optional): Micromark extensions to change how markdown is parsed.
• mdastExtensions (Array<Extension | Array<Extension>>, optional): Extensions for this utility to change how tokens are turned into an mdast tree.

You can extend the parsing behavior of fromMarkdown() by providing custom extensions via the mdastExtensions option. These extensions are passed to the internal compiler configuration to modify how tokens are handled or to add new node types.

import { fromMarkdown } from 'mdast-util-from-markdown'

const tree = fromMarkdown('some markdown', undefined, {
  mdastExtensions: [/* your custom extensions here */]
})

The fromMarkdown() function is the primary entry point for converting a Markdown string (or Buffer) into a Markdown Abstract Syntax Tree (mdast). It uses micromark for parsing and applies transformations to produce a structured tree.

Signature

fromMarkdown(value[, encoding][, options])

• value: The Markdown string or Buffer to parse.
• encoding (optional): The character encoding to use if value is a Buffer.
• options (optional): Configuration object of type Options.

Usage

If you provide an object as the second argument, it is treated as the options object, and encoding is ignored.

import { fromMarkdown } from 'mdast-util-from-markdown'

const tree = fromMarkdown('## Hello *World*')
// Returns an mdast Root node