What is mdast-util-from-markdown?
The mdast-util-from-markdown package is a utility to parse Markdown and convert it into a Markdown Abstract Syntax Tree (MDAST). It allows developers to work with the tree structure to manipulate, inspect, or transform Markdown content programmatically.
What are mdast-util-from-markdown's main functionalities?
Parsing Markdown to MDAST
This feature allows you to parse a Markdown string and produce an MDAST. The MDAST can then be manipulated or inspected as needed.
import { fromMarkdown } from 'mdast-util-from-markdown';
const mdast = fromMarkdown('# Hello world');
Using plugins to extend parsing capabilities
This feature enables the use of plugins to extend the parsing capabilities of the utility. For example, using the 'micromark-extension-gfm' plugin to support GitHub Flavored Markdown (GFM) features like task lists.
import { fromMarkdown } from 'mdast-util-from-markdown';
import gfm from 'micromark-extension-gfm';
const mdast = fromMarkdown('# Hello world\n\n- [ ] task list item', {extensions: [gfm()]});
Other packages similar to mdast-util-from-markdown
remark-parse
Remark-parse is a plugin for the remark processor that parses Markdown into an MDAST. It is part of the unified ecosystem and is similar to mdast-util-from-markdown but is typically used as part of the remark ecosystem.
markdown-it
Markdown-it is a Markdown parser with a focus on speed and extensibility. It can be used to parse Markdown into a syntax tree, which is similar to MDAST but with its own structure. It differs from mdast-util-from-markdown in that it is a full parser and renderer, not just a utility for producing an AST.
marked
Marked is a Markdown parser and compiler that is designed for speed. It produces an abstract syntax tree that can be used similarly to MDAST, but it is not directly compatible with the unified ecosystem like mdast-util-from-markdown is.
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 import
ed instead of require
d.
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.
Related
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