unified

Project: syntax-tree/mdast-util-from-markdown

Package: mdast-util-from-markdown@1.0.0

  1. Dependents: 32
  2. mdast utility to parse markdown
  1. util 143
  2. utility 139
  3. markdown 132
  4. unist 126
  5. mdast 85
  6. tree 41
  7. ast 31
  8. mdast-util 30
  9. syntax 28
  10. parse 22
  11. markup 18

mdast-util-from-markdown

Build Coverage Downloads Size Sponsors Backers Chat

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

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.

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