mdast-util-to-hast
Advanced tools
The mdast-util-to-hast package is a utility that allows for the transformation of MDAST (Markdown Abstract Syntax Tree) to HAST (Hypertext Abstract Syntax Tree). This is particularly useful for applications that need to convert markdown content into HTML or other formats that can be more easily manipulated or displayed in web environments.
Convert MDAST to HAST
This feature allows for the conversion of a markdown document represented as an MDAST into a HAST. The code sample demonstrates how to use unified with the remark-parse plugin to parse markdown into MDAST, and then convert that MDAST into HAST using mdast-util-to-hast.
const unified = require('unified')
const markdown = require('remark-parse')
const toHAST = require('mdast-util-to-hast')
unified()
.use(markdown)
.use(() => tree => toHAST(tree))
.process('# Hello world!', function (err, file) {
if (err) throw err
console.log(file)
})remark-html is a plugin for the remark processor that compiles markdown to HTML. It is similar to mdast-util-to-hast in that it also deals with the conversion of markdown content to a more web-friendly format. However, remark-html is more of an end-to-end solution for converting markdown directly to HTML, whereas mdast-util-to-hast provides a lower-level conversion to HAST, which can then be further manipulated or converted to HTML.
rehype is a processor powered by plugins part of the unified ecosystem that manipulates HTML documents. It is similar to mdast-util-to-hast in the sense that both deal with HAST nodes. However, rehype operates directly on HTML content or HAST, focusing on the manipulation and processing of HTML, whereas mdast-util-to-hast is specifically designed for converting MDAST to HAST.
mdast utility to transform to hast.
This package is a utility that takes an mdast (markdown) syntax tree as input and turns it into a hast (HTML) syntax tree.
This project is useful when you want to deal with ASTs and turn markdown to HTML.
The hast utility hast-util-to-mdast does the inverse of
this utility.
It turns HTML into markdown.
The remark plugin remark-rehype wraps this utility to also
turn markdown to HTML at a higher-level (easier) abstraction.
This package is ESM only. In Node.js (version 16+), install with npm:
npm install mdast-util-to-hast
In Deno with esm.sh:
import {toHast} from 'https://esm.sh/mdast-util-to-hast@13'
In browsers with esm.sh:
<script type="module">
import {toHast} from 'https://esm.sh/mdast-util-to-hast@13?bundle'
</script>
Say we have the following example.md:
## Hello **World**!
…and next to it a module example.js:
import {fs} from 'node:fs/promises'
import {toHtml} from 'hast-util-to-html'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toHast} from 'mdast-util-to-hast'
const markdown = String(await fs.readFile('example.md'))
const mdast = fromMarkdown(markdown)
const hast = toHast(mdast)
const html = toHtml(hast)
console.log(html)
…now running node example.js yields:
<h2>Hello <strong>World</strong>!</h2>
This package exports the identifiers
defaultFootnoteBackContent,
defaultFootnoteBackLabel,
defaultHandlers, and
toHast.
There is no default export.
defaultFootnoteBackContent(referenceIndex, rereferenceIndex)Generate the default content that GitHub uses on backreferences.
referenceIndex (number)
— index of the definition in the order that they are first referenced,
0-indexedrereferenceIndex (number)
— index of calls to the same definition, 0-indexedContent (Array<ElementContent>).
defaultFootnoteBackLabel(referenceIndex, rereferenceIndex)Generate the default label that GitHub uses on backreferences.
referenceIndex (number)
— index of the definition in the order that they are first referenced,
0-indexedrereferenceIndex (number)
— index of calls to the same definition, 0-indexedLabel (string).
defaultHandlersDefault handlers for nodes (Handlers).
toHast(tree[, options])Transform mdast to hast.
hast tree (HastNode).
Raw HTML is available in mdast as html nodes and can be embedded
in hast as semistandard raw nodes.
Most utilities ignore raw nodes but two notable ones don’t:
hast-util-to-html also has an option
allowDangerousHtml which will output the raw HTML.
This is typically discouraged as noted by the option name but is useful if
you completely trust authorshast-util-raw can handle the raw embedded HTML strings by
parsing them into standard hast nodes (element, text, etc).
This is a heavy task as it needs a full HTML parser, but it is the only way
to support untrusted contentMany options supported here relate to footnotes.
Footnotes are not specified by CommonMark, which we follow by default.
They are supported by GitHub, so footnotes can be enabled in markdown with
mdast-util-gfm.
The options footnoteBackLabel and footnoteLabel define natural language
that explains footnotes, which is hidden for sighted users but shown to
assistive technology.
When your page is not in English, you must define translated values.
Back references use ARIA attributes, but the section label itself uses a
heading that is hidden with an sr-only class.
To show it to sighted users, define different attributes in
footnoteLabelProperties.
Footnotes introduces a problem, as it links footnote calls to footnote
definitions on the page through id attributes generated from user content,
which results in DOM clobbering.
DOM clobbering is this:
<p id=x></p>
<script>alert(x) // `x` now refers to the DOM `p#x` element</script>
Elements by their ID are made available by browsers on the window object,
which is a security risk.
Using a prefix solves this problem.
More information on how to handle clobbering and the prefix is explained in
Example: headings (DOM clobbering) in rehype-sanitize.
Unknown nodes are nodes with a type that isn’t in handlers or passThrough.
The default behavior for unknown nodes is:
value (and doesn’t have data.hName,
data.hProperties, or data.hChildren, see later), create a hast text
node<div> element (which could be changed with
data.hName), with its children mapped from mdast to hast as wellThis behavior can be changed by passing an unknownHandler.
FootnoteBackContentTemplateGenerate content for the backreference dynamically.
For the following markdown:
Alpha[^micromark], bravo[^micromark], and charlie[^remark].
[^remark]: things about remark
[^micromark]: things about micromark
This function will be called with:
0 and 0 for the backreference from things about micromark to
alpha, as it is the first used definition, and the first call to it0 and 1 for the backreference from things about micromark to
bravo, as it is the first used definition, and the second call to it1 and 0 for the backreference from things about remark to
charlie, as it is the second used definitionreferenceIndex (number)
— index of the definition in the order that they are first referenced,
0-indexedrereferenceIndex (number)
— index of calls to the same definition, 0-indexedContent for the backreference when linking back from definitions to their
reference (Array<ElementContent>, ElementContent, or string).
FootnoteBackLabelTemplateGenerate a back label dynamically.
For the following markdown:
Alpha[^micromark], bravo[^micromark], and charlie[^remark].
[^remark]: things about remark
[^micromark]: things about micromark
This function will be called with:
0 and 0 for the backreference from things about micromark to
alpha, as it is the first used definition, and the first call to it0 and 1 for the backreference from things about micromark to
bravo, as it is the first used definition, and the second call to it1 and 0 for the backreference from things about remark to
charlie, as it is the second used definitionreferenceIndex (number)
— index of the definition in the order that they are first referenced,
0-indexedrereferenceIndex (number)
— index of calls to the same definition, 0-indexedBack label to use when linking back from definitions to their reference
(string).
HandlerHandle a node (TypeScript type).
state (State)
— info passed aroundnode (MdastNode)
— node to handleparent (MdastNode | undefined)
— parent of nodeResult (Array<HastNode> | HastNode | undefined).
HandlersHandle nodes (TypeScript type).
type Handlers = Partial<Record<Nodes['type'], Handler>>
OptionsConfiguration (TypeScript type).
allowDangerousHtml (boolean, default: false)
— whether to persist raw HTML in markdown in the hast treeclobberPrefix (string, default: 'user-content-')
— prefix to use before the id property on footnotes to prevent them from
clobberingfootnoteBackContent
(FootnoteBackContentTemplate
or string, default:
defaultFootnoteBackContent)
— content of the backreference back to referencesfootnoteBackLabel
(FootnoteBackLabelTemplate
or string, default:
defaultFootnoteBackLabel)
— label to describe the backreference back to referencesfootnoteLabel (string, default: 'Footnotes')
— label to use for the footnotes section (affects screen readers)footnoteLabelProperties
(Properties, default: {className: ['sr-only']})
— properties to use on the footnote label
(note that id: 'footnote-label' is always added as footnote calls use it
with aria-describedby to provide an accessible label)footnoteLabelTagName (string, default: h2)
— tag name to use for the footnote labelhandlers (Handlers, optional)
— extra handlers for nodespassThrough (Array<Nodes['type']>, optional)
— list of custom mdast node types to pass through (keep) in hast (note that
the node itself is passed, but eventual children are transformed)unknownHandler (Handler, optional)
— handle all unknown nodesRawRaw string of HTML embedded into HTML AST (TypeScript type).
import type {Data, Literal} from 'hast'
interface Raw extends Literal {
type: 'raw'
data?: RawData | undefined
}
interface RawData extends Data {}
StateInfo passed around about the current state (TypeScript type).
all ((node: MdastNode) => Array<HastNode>)
— transform the children of an mdast parent to hastapplyData (<Type extends HastNode>(from: MdastNode, to: Type) => Type | HastElement)
— honor the data of from and maybe generate an element instead of todefinitionById (Map<string, Definition>)
— definitions by their uppercased identifierfootnoteById (Map<string, FootnoteDefinition>)
— footnote definitions by their uppercased identifierfootnoteCounts (Map<string, number>)
— counts for how often the same footnote was calledfootnoteOrder (Array<string>)
— identifiers of order when footnote calls first appear in tree orderhandlers (Handlers)
— applied node handlersone ((node: MdastNode, parent: MdastNode | undefined) => HastNode | Array<HastNode> | undefined)
— transform an mdast node to hastoptions (Options)
— configurationpatch ((from: MdastNode, to: HastNode) => undefined)wrap (<Type extends HastNode>(nodes: Array<Type>, loose?: boolean) => Array<Type | HastText>)
— wrap nodes with line endings between each node, adds initial/final line
endings when looseIf you completely trust authors (or plugins) and want to allow them to HTML in
markdown, and the last utility has an allowDangerousHtml option as well (such
as hast-util-to-html) you can pass allowDangerousHtml to this utility
(mdast-util-to-hast):
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toHast} from 'mdast-util-to-hast'
import {toHtml} from 'hast-util-to-html'
const markdown = 'It <i>works</i>! <img onerror="alert(1)">'
const mdast = fromMarkdown(markdown)
const hast = toHast(mdast, {allowDangerousHtml: true})
const html = toHtml(hast, {allowDangerousHtml: true})
console.log(html)
…now running node example.js yields:
<p>It <i>works</i>! <img onerror="alert(1)"></p>
⚠️ Danger: observe that the XSS attack through the
onerrorattribute is still present.
If you do not trust the authors of the input markdown, or if you want to make
sure that further utilities can see HTML embedded in markdown, use
hast-util-raw.
The following example passes allowDangerousHtml to this utility
(mdast-util-to-hast), then turns the raw embedded HTML into proper HTML nodes
(hast-util-raw), and finally sanitizes the HTML by only allowing safe things
(hast-util-sanitize):
import {raw} from 'hast-util-raw'
import {sanitize} from 'hast-util-sanitize'
import {toHtml} from 'hast-util-to-html'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toHast} from 'mdast-util-to-hast'
const markdown = 'It <i>works</i>! <img onerror="alert(1)">'
const mdast = fromMarkdown(markdown)
const hast = raw(toHast(mdast, {allowDangerousHtml: true}))
const safeHast = sanitize(hast)
const html = toHtml(safeHast)
console.log(html)
…now running node example.js yields:
<p>It <i>works</i>! <img></p>
👉 Note: observe that the XSS attack through the
onerrorattribute is no longer present.
If you know that the markdown is authored in a language other than English,
and you’re using micromark-extension-gfm and mdast-util-gfm to match how
GitHub renders markdown, and you know that footnotes are (or can?) be used, you
should translate the labels associated with them.
Let’s first set the stage:
import {toHtml} from 'hast-util-to-html'
import {gfm} from 'micromark-extension-gfm'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmFromMarkdown} from 'mdast-util-gfm'
import {toHast} from 'mdast-util-to-hast'
const markdown = 'Bonjour[^1]\n\n[^1]: Monde!'
const mdast = fromMarkdown(markdown, {
extensions: [gfm()],
mdastExtensions: [gfmFromMarkdown()]
})
const hast = toHast(mdast)
const html = toHtml(hast)
console.log(html)
…now running node example.js yields:
<p>Bonjour<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>
<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
<ol>
<li id="user-content-fn-1">
<p>Monde! <a href="#user-content-fnref-1" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a></p>
</li>
</ol>
</section>
This is a mix of English and French that screen readers can’t handle nicely. Let’s say our program does know that the markdown is in French. In that case, it’s important to translate and define the labels relating to footnotes so that screen reader users can properly pronounce the page:
@@ -9,7 +9,16 @@ const mdast = fromMarkdown(markdown, {
extensions: [gfm()],
mdastExtensions: [gfmFromMarkdown()]
})
-const hast = toHast(mdast)
+const hast = toHast(mdast, {
+ footnoteLabel: 'Notes de bas de page',
+ footnoteBackLabel(referenceIndex, rereferenceIndex) {
+ return (
+ 'Retour à la référence ' +
+ (referenceIndex + 1) +
+ (rereferenceIndex > 1 ? '-' + rereferenceIndex : '')
+ )
+ }
+})
const html = toHtml(hast)
console.log(html)
…now running node example.js with the above patch applied yields:
@@ -1,8 +1,8 @@
<p>Bonjour<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>
-<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
+<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Notes de bas de page</h2>
<ol>
<li id="user-content-fn-1">
-<p>Monde! <a href="#user-content-fnref-1" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a></p>
+<p>Monde! <a href="#user-content-fnref-1" data-footnote-backref="" aria-label="Retour à la référence 1" class="data-footnote-backref">↩</a></p>
</li>
</ol>
</section>
This project supports CommonMark and the GFM constructs (footnotes, strikethrough, tables) and the frontmatter constructs YAML and TOML. Support can be extended to other constructs in two ways: a) with handlers, b) through fields on nodes.
For example, when we represent a mark element in markdown and want to turn it
into a <mark> element in HTML, we can use a handler:
import {toHtml} from 'hast-util-to-html'
import {toHast} from 'mdast-util-to-hast'
const mdast = {
type: 'paragraph',
children: [{type: 'mark', children: [{type: 'text', value: 'x'}]}]
}
const hast = toHast(mdast, {
handlers: {
mark(state, node) {
return {
type: 'element',
tagName: 'mark',
properties: {},
children: state.all(node)
}
}
}
})
console.log(toHtml(hast))
We can do the same through certain fields on nodes:
import {toHtml} from 'hast-util-to-html'
import {toHast} from 'mdast-util-to-hast'
const mdast = {
type: 'paragraph',
children: [
{
type: 'mark',
children: [{type: 'text', value: 'x'}],
data: {hName: 'mark'}
}
]
}
console.log(toHtml(toHast(mdast)))
This project by default handles CommonMark, GFM (footnotes, strikethrough, tables) and common frontmatter (YAML, TOML).
Existing handlers can be overwritten and handlers for more nodes can be added. It’s also possible to define how mdast is turned into hast through fields on nodes.
The following table gives insight into what input turns into what output:
| mdast node | markdown example | hast node | html example |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
|
|
|
|
|
| |
|
|
| |
|
|
| |
|
Nothing (default), |
n/a | |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
| ||
|
|
| |
|
| ||
|
|
| |
|
|
| |
|
|
|
Nothing |
n/a |
|
|
|
Nothing |
n/a |
👉 Note: GFM prescribes that the obsolete
alignattribute ontdandthelements is used. To usestyleattributes instead of obsolete features, combine this utility with@mapbox/hast-util-table-cell-style.
🧑🏫 Info: this project is concerned with turning one syntax tree into another. It does not deal with markdown syntax or HTML syntax. The preceding examples are illustrative rather than authoritative or exhaustive.
A frequent problem arises when having to turn one syntax tree into another. As the original tree (in this case, mdast for markdown) is in some cases limited compared to the destination (in this case, hast for HTML) tree, is it possible to provide more info in the original to define what the result will be in the destination? This is possible by defining data on mdast nodes, which this utility will read as instructions on what hast nodes to create.
An example is math, which is a nonstandard markdown extension, that this utility
doesn’t understand.
To solve this, mdast-util-math defines instructions on mdast nodes that this
plugin does understand because they define a certain hast structure.
The following fields can be used:
node.data.hName — define the element’s tag namenode.data.hProperties — define extra properties to usenode.data.hChildren — define hast children to usehNamenode.data.hName sets the tag name of an element.
The following mdast:
{
type: 'strong',
data: {hName: 'b'},
children: [{type: 'text', value: 'Alpha'}]
}
…yields (hast):
{
type: 'element',
tagName: 'b',
properties: {},
children: [{type: 'text', value: 'Alpha'}]
}
hPropertiesnode.data.hProperties sets the properties of an element.
The following mdast:
{
type: 'image',
src: 'circle.svg',
alt: 'Big red circle on a black background',
data: {hProperties: {className: ['responsive']}}
}
…yields (hast):
{
type: 'element',
tagName: 'img',
properties: {
src: 'circle.svg',
alt: 'Big red circle on a black background',
className: ['responsive']
},
children: []
}
hChildrennode.data.hChildren sets the children of an element.
The following mdast:
{
type: 'code',
lang: 'js',
data: {
hChildren: [
{
type: 'element',
tagName: 'span',
properties: {className: ['hljs-meta']},
children: [{type: 'text', value: '"use strict"'}]
},
{type: 'text', value: ';'}
]
},
value: '"use strict";'
}
…yields (hast):
{
type: 'element',
tagName: 'pre',
properties: {},
children: [{
type: 'element',
tagName: 'code',
properties: {className: ['language-js']},
children: [
{
type: 'element',
tagName: 'span',
properties: {className: ['hljs-meta']},
children: [{type: 'text', value: '"use strict"'}]
},
{type: 'text', value: ';'}
]
}]
}
👉 Note: the
preandlanguage-jsclass are normalmdast-util-to-hastfunctionality.
Assuming you know how to use (semantic) HTML and CSS, then it should generally be straightforward to style the HTML produced by this plugin. With CSS, you can get creative and style the results as you please.
Some semistandard features, notably GFMs tasklists and footnotes, generate HTML
that be unintuitive, as it matches exactly what GitHub produces for their
website.
There is a project, sindresorhus/github-markdown-css,
that exposes the stylesheet that GitHub uses for rendered markdown, which might
either be inspirational for more complex features, or can be used as-is to
exactly match how GitHub styles rendered markdown.
The following CSS is needed to make footnotes look a bit like GitHub:
/* Style the footnotes section. */
.footnotes {
font-size: smaller;
color: #8b949e;
border-top: 1px solid #30363d;
}
/* Hide the section label for visual users. */
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
overflow: hidden;
clip: rect(0, 0, 0, 0);
word-wrap: normal;
border: 0;
}
/* Place `[` and `]` around footnote calls. */
[data-footnote-ref]::before {
content: '[';
}
[data-footnote-ref]::after {
content: ']';
}
The following interfaces are added to hast by this utility.
Rawinterface Raw <: Literal {
type: 'raw'
}
Raw (Literal) represents a string if raw HTML inside
hast.
Raw nodes are typically ignored but are handled by
hast-util-to-html and hast-util-raw.
This package is fully typed with TypeScript.
It exports the
FootnoteBackContentTemplate,
FootnoteBackLabelTemplate,
Handler,
Handlers,
Options,
Raw, and
State types.
It also registers the Raw node type with @types/hast.
If you’re working with the syntax tree (and you pass
allowDangerousHtml: true), make sure to import this utility somewhere in your
types, as that registers the new node type in the tree.
/**
* @typedef {import('mdast-util-to-hast')}
*/
import {visit} from 'unist-util-visit'
/** @type {import('hast').Root} */
const tree = { /* … */ }
visit(tree, function (node) {
// `node` can now be `raw`.
})
Finally, it also registers the hChildren, hName, and hProperties fields
on Data of @types/mdast.
If you’re working with the syntax tree, make sure to import this utility
somewhere in your types, as that registers the data fields in the tree.
/**
* @typedef {import('mdast-util-to-hast')}
*/
import {visit} from 'unist-util-visit'
/** @type {import('hast').Root} */
const tree = { /* … */ }
console.log(tree.data?.hName) // Types as `string | undefined`.
Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, mdast-util-to-hast@^13,
compatible with Node.js 16.
Use of mdast-util-to-hast can open you up to a
cross-site scripting (XSS) attack.
Embedded hast properties (hName, hProperties, hChildren), custom handlers,
and the allowDangerousHtml option all provide openings.
The following example shows how a script is injected where a benign code block is expected with embedded hast properties:
const code = {type: 'code', value: 'alert(1)'}
code.data = {hName: 'script'}
Yields:
<script>alert(1)</script>
The following example shows how an image is changed to fail loading and therefore run code in a browser.
const image = {type: 'image', url: 'existing.png'}
image.data = {hProperties: {src: 'missing', onError: 'alert(2)'}}
Yields:
<img src="missing" onerror="alert(2)">
The following example shows the default handling of embedded HTML:
# Hello
<script>alert(3)</script>
Yields:
<h1>Hello</h1>
Passing allowDangerousHtml: true to mdast-util-to-hast is typically still
not enough to run unsafe code:
<h1>Hello</h1>
<script>alert(3)</script>
If allowDangerousHtml: true is also given to hast-util-to-html (or
rehype-stringify), the unsafe code runs:
<h1>Hello</h1>
<script>alert(3)</script>
Use hast-util-sanitize to make the hast tree safe.
hast-util-to-mdast
— transform hast to mdasthast-util-to-xast
— transform hast to xasthast-util-sanitize
— sanitize hast nodesSee 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.
FAQs
mdast utility to transform to hast
The npm package mdast-util-to-hast receives a total of 5,162,399 weekly downloads. As such, mdast-util-to-hast popularity was classified as popular.
We found that mdast-util-to-hast demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.