mdast-util-from-markdown

mdast utility to parse markdown.

When to use this

Use this if you want to use micromark but need an AST. Use remark instead, which includes both to provide a nice interface and hundreds of plugins.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install mdast-util-from-markdown

Use

Say we have the following markdown file, example.md:

## Hello, *World*!

And our script, example.js, looks as follows:

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

const doc = fs.readFileSync('example.md')

const tree = fromMarkdown(doc)

console.log(tree)

Now, running node example yields (positional info removed for brevity):

{
  type: 'root',
  children: [
    {
      type: 'heading',
      depth: 2,
      children: [
        {type: 'text', value: 'Hello, '},
        {
          type: 'emphasis',
          children: [{type: 'text', value: 'World'}]
        },
        {type: 'text', value: '!'}
      ]
    }
  ]
}

API

This package exports the following identifier: fromMarkdown. There is no default export.

The export map supports the endorsed development condition. Run node --conditions development module.js to get instrumented dev code. Without this condition, production code is loaded.

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

Parse markdown to a mdast tree.

Parameters

doc

Value to parse (string or Buffer).

encoding

Character encoding to understand doc as when it’s a Buffer (string, default: 'utf8').

options.extensions

Array of syntax extensions (Array.<MicromarkSyntaxExtension>, default: []). Passed to micromark as extensions.

options.mdastExtensions

Array of mdast extensions (Array.<MdastExtension>, default: []).

Returns

Root.

List of extensions

• syntax-tree/mdast-util-directive — parse directives
• syntax-tree/mdast-util-footnote — parse footnotes
• syntax-tree/mdast-util-frontmatter — parse frontmatter (YAML, TOML, more)
• syntax-tree/mdast-util-gfm — parse GFM
• syntax-tree/mdast-util-gfm-autolink-literal — parse GFM autolink literals
• syntax-tree/mdast-util-gfm-strikethrough — parse GFM strikethrough
• syntax-tree/mdast-util-gfm-table — parse GFM tables
• syntax-tree/mdast-util-gfm-task-list-item — parse GFM task list items
• syntax-tree/mdast-util-math — parse math
• syntax-tree/mdast-util-mdx — parse MDX or MDX.js
• syntax-tree/mdast-util-mdx-expression — parse MDX or MDX.js expressions
• syntax-tree/mdast-util-mdx-jsx — parse MDX or MDX.js JSX
• syntax-tree/mdast-util-mdxjs-esm — parse MDX.js ESM

Security

As markdown is sometimes used for HTML, and improper use of HTML can open you up to a cross-site scripting (XSS) attack, use of mdast-util-from-markdown can also be unsafe. When going to HTML, use this utility in combination with hast-util-sanitize to make the tree safe.

Related

• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• remarkjs/remark — markdown processor powered by plugins
• syntax-tree/mdast-util-to-markdown — serialize mdast to markdown

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer