` element (which could be changed with
`data.hName`), with its children mapped from mdast to hast as well
This behavior can be changed by passing an `unknownHandler`.
### `FootnoteBackContentTemplate`
Generate content for the backreference dynamically.
For the following markdown:
```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 it
* `0` and `1` for the backreference from `things about micromark` to
`bravo`, as it is the first used definition, and the second call to it
* `1` and `0` for the backreference from `things about remark` to
`charlie`, as it is the second used definition
###### Parameters
* `referenceIndex` (`number`)
— index of the definition in the order that they are first referenced,
0-indexed
* `rereferenceIndex` (`number`)
— index of calls to the same definition, 0-indexed
###### Returns
Content for the backreference when linking back from definitions to their
reference (`Array`, `ElementContent`, or `string`).
### `FootnoteBackLabelTemplate`
Generate a back label dynamically.
For the following markdown:
```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 it
* `0` and `1` for the backreference from `things about micromark` to
`bravo`, as it is the first used definition, and the second call to it
* `1` and `0` for the backreference from `things about remark` to
`charlie`, as it is the second used definition
###### Parameters
* `referenceIndex` (`number`)
— index of the definition in the order that they are first referenced,
0-indexed
* `rereferenceIndex` (`number`)
— index of calls to the same definition, 0-indexed
###### Returns
Back label to use when linking back from definitions to their reference
(`string`).
### `Handler`
Handle a node (TypeScript type).
###### Parameters
* `state` ([`State`][api-state])
— info passed around
* `node` ([`MdastNode`][mdast-node])
— node to handle
* `parent` ([`MdastNode | undefined`][mdast-node])
— parent of `node`
###### Returns
Result ([`Array | HastNode | undefined`][hast-node]).
### `Handlers`
Handle nodes (TypeScript type).
###### Type
```ts
type Handlers = Partial>
```
### `Options`
Configuration (TypeScript type).
###### Fields
* `allowDangerousHtml` (`boolean`, default: `false`)
— whether to persist raw HTML in markdown in the hast tree
* `clobberPrefix` (`string`, default: `'user-content-'`)
— prefix to use before the `id` property on footnotes to prevent them from
*clobbering*
* `file` ([`VFile`][vfile], optional)
— corresponding virtual file representing the input document
* `footnoteBackContent`
([`FootnoteBackContentTemplate`][api-footnote-back-content-template]
or `string`, default:
[`defaultFootnoteBackContent`][api-default-footnote-back-content])
— content of the backreference back to references
* `footnoteBackLabel`
([`FootnoteBackLabelTemplate`][api-footnote-back-label-template]
or `string`, default:
[`defaultFootnoteBackLabel`][api-default-footnote-back-label])
— label to describe the backreference back to references
* `footnoteLabel` (`string`, default: `'Footnotes'`)
— label to use for the footnotes section (affects screen readers)
* `footnoteLabelProperties`
([`Properties`][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 label
* `handlers` ([`Handlers`][api-handlers], optional)
— extra handlers for nodes
* `passThrough` (`Array`, 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`][api-handler], optional)
— handle all unknown nodes
### `Raw`
Raw string of HTML embedded into HTML AST (TypeScript type).
###### Type
```ts
import type {Data, Literal} from 'hast'
interface Raw extends Literal {
type: 'raw'
data?: RawData | undefined
}
interface RawData extends Data {}
```
### `State`
Info passed around about the current state (TypeScript type).
###### Fields
* `all` (`(node: MdastNode) => Array`)
— transform the children of an mdast parent to hast
* `applyData` (`(from: MdastNode, to: Type) => Type | HastElement`)
— honor the `data` of `from` and maybe generate an element instead of `to`
* `definitionById` (`Map`)
— definitions by their uppercased identifier
* `footnoteById` (`Map`)
— footnote definitions by their uppercased identifier
* `footnoteCounts` (`Map`)
— counts for how often the same footnote was called
* `footnoteOrder` (`Array`)
— identifiers of order when footnote calls first appear in tree order
* `handlers` ([`Handlers`][api-handlers])
— applied node handlers
* `one` (`(node: MdastNode, parent: MdastNode | undefined) => HastNode | Array | undefined`)
— transform an mdast node to hast
* `options` ([`Options`][api-options])
— configuration
* `patch` (`(from: MdastNode, to: HastNode) => undefined`)
* `wrap` (`(nodes: Array, loose?: boolean) => Array`)
— wrap `nodes` with line endings between each node, adds initial/final line
endings when `loose`
## Examples
### Example: supporting HTML in markdown naïvely
If 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`):
```js
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toHast} from 'mdast-util-to-hast'
import {toHtml} from 'hast-util-to-html'
const markdown = 'It works! ![]()
'
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:
```html
![]()
'
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:
```html
> 👉 **Note**: GFM prescribes that the obsolete `align` attribute on `td` and
> `th` elements is used.
> To use `style` attributes instead of obsolete features, combine this utility
> with [`@mapbox/hast-util-table-cell-style`][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.
### Fields on nodes
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 name
* `node.data.hProperties` — define extra properties to use
* `node.data.hChildren` — define hast children to use
###### `hName`
`node.data.hName` sets the tag name of an element.
The following [mdast][]:
```js
{
type: 'strong',
data: {hName: 'b'},
children: [{type: 'text', value: 'Alpha'}]
}
```
…yields ([hast][]):
```js
{
type: 'element',
tagName: 'b',
properties: {},
children: [{type: 'text', value: 'Alpha'}]
}
```
###### `hProperties`
`node.data.hProperties` sets the properties of an element.
The following [mdast][]:
```js
{
type: 'image',
src: 'circle.svg',
alt: 'Big red circle on a black background',
data: {hProperties: {className: ['responsive']}}
}
```
…yields ([hast][]):
```js
{
type: 'element',
tagName: 'img',
properties: {
src: 'circle.svg',
alt: 'Big red circle on a black background',
className: ['responsive']
},
children: []
}
```
###### `hChildren`
`node.data.hChildren` sets the children of an element.
The following [mdast][]:
```js
{
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][]):
```js
{
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 `pre` and `language-js` class are normal `mdast-util-to-hast`
> functionality.
## CSS
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`][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:
```css
/* 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: ']';
}
```
## Syntax tree
The following interfaces are added to **[hast][]** by this utility.
### Nodes
#### `Raw`
```idl
interface Raw <: Literal {
type: 'raw'
}
```
**Raw** (**[Literal][dfn-literal]**) represents a string if raw HTML inside
hast.
Raw nodes are typically ignored but are handled by
[`hast-util-to-html`][hast-util-to-html] and [`hast-util-raw`][hast-util-raw].
## Types
This package is fully typed with [TypeScript][].
It exports the
[`FootnoteBackContentTemplate`][api-footnote-back-content-template],
[`FootnoteBackLabelTemplate`][api-footnote-back-label-template],
[`Handler`][api-handler],
[`Handlers`][api-handlers],
[`Options`][api-options],
[`Raw`][api-raw], and
[`State`][api-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.
```js
/**
* @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.
```js
/**
* @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`.
```
## Compatibility
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.
## Security
Use of `mdast-util-to-hast` can open you up to a
[cross-site scripting (XSS)][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:
```js
const code = {type: 'code', value: 'alert(1)'}
code.data = {hName: 'script'}
```
Yields:
```html
```
The following example shows how an image is changed to fail loading and
therefore run code in a browser.
```js
const image = {type: 'image', url: 'existing.png'}
image.data = {hProperties: {src: 'missing', onError: 'alert(2)'}}
```
Yields:
```html
```
The following example shows the default handling of embedded HTML:
```markdown
# Hello
```
Yields:
```html
It works!
It works!
Bonjour1
Footnotes
-
Monde! ↩
Bonjour1
-Footnotes
+Notes de bas de page
| mdast node | markdown example | hast node | html example | |
|---|---|---|---|---|
| [`blockquote`](https://github.com/syntax-tree/mdast#blockquote) | ```markdown > A greater than… ``` | [`element`](https://github.com/syntax-tree/hast#element) (`blockquote`) |
```html
``` |
|
| [`break`](https://github.com/syntax-tree/mdast#break) | ```markdown A backslash\ before a line break… ``` | [`element`](https://github.com/syntax-tree/hast#element) (`br`) |
```html
A backslash |
|
| [`code`](https://github.com/syntax-tree/mdast#code) | ````markdown ```js backtick.fences('for blocks') ``` ```` | [`element`](https://github.com/syntax-tree/hast#element) (`pre` and `code`) |
```html
|
|
| [`delete`](https://github.com/syntax-tree/mdast#delete) (GFM) | ```markdown Two ~~tildes~~ for delete. ``` | [`element`](https://github.com/syntax-tree/hast#element) (`del`) |
```html
Two |
|
| [`emphasis`](https://github.com/syntax-tree/mdast#emphasis) | ```markdown Some *asterisks* for emphasis. ``` | [`element`](https://github.com/syntax-tree/hast#element) (`em`) |
```html
Some asterisks for emphasis. ``` |
|
| [`footnoteReference`](https://github.com/syntax-tree/mdast#footnotereference), [`footnoteDefinition`](https://github.com/syntax-tree/mdast#footnotedefinition) (GFM) | ```markdown With a [^caret]. [^caret]: Stuff ``` | [`element`](https://github.com/syntax-tree/hast#element) (`section`, `sup`, `a`) |
```html
With a 1. … ``` |
|
| [`heading`](https://github.com/syntax-tree/mdast#heading) | ```markdown # One number sign… ###### Six number signs… ``` | [`element`](https://github.com/syntax-tree/hast#element) (`h1`…`h6`) |
```html
One number sign…Six number signs…``` |
|
| [`html`](https://github.com/syntax-tree/mdast#html) | ```html CMD+S ``` | Nothing (default), `raw` (when `allowDangerousHtml: true`) | n/a | |
| [`image`](https://github.com/syntax-tree/mdast#image) | ```markdown  ``` | [`element`](https://github.com/syntax-tree/hast#element) (`img`) |
```html
|
|
| [`imageReference`](https://github.com/syntax-tree/mdast#imagereference), [`definition`](https://github.com/syntax-tree/mdast#definition) | ```markdown ![Alt text][logo] [logo]: /logo.png "title" ``` | [`element`](https://github.com/syntax-tree/hast#element) (`img`) |
```html
|
|
| [`inlineCode`](https://github.com/syntax-tree/mdast#inlinecode) | ```markdown Some `backticks` for inline code. ``` | [`element`](https://github.com/syntax-tree/hast#element) (`code`) |
```html
Some |
|
| [`link`](https://github.com/syntax-tree/mdast#link) | ```markdown [Example](https://example.com "title") ``` | [`element`](https://github.com/syntax-tree/hast#element) (`a`) | ```html ``` | |
| [`linkReference`](https://github.com/syntax-tree/mdast#linkreference), [`definition`](https://github.com/syntax-tree/mdast#definition) | ```markdown [Example][] [example]: https://example.com "title" ``` | [`element`](https://github.com/syntax-tree/hast#element) (`a`) | ```html ``` | |
| [`list`](https://github.com/syntax-tree/mdast#list), [`listItem`](https://github.com/syntax-tree/mdast#listitem) | ```markdown * asterisks for unordered items 1. decimals and a dot for ordered items ``` | [`element`](https://github.com/syntax-tree/hast#element) (`li` and `ol` or `ul`) |
```html
|
|
| [`paragraph`](https://github.com/syntax-tree/mdast#paragraph) | ```markdown Just some text… ``` | [`element`](https://github.com/syntax-tree/hast#element) (`p`) |
```html
Just some text… ``` |
|
| [`root`](https://github.com/syntax-tree/mdast#root) | ```markdown Anything! ``` | [`root`](https://github.com/syntax-tree/hast#root) |
```html
Anything! ``` |
|
| [`strong`](https://github.com/syntax-tree/mdast#strong) | ```markdown Two **asterisks** for strong. ``` | [`element`](https://github.com/syntax-tree/hast#element) (`strong`) |
```html
Two asterisks for strong. ``` |
|
| [`text`](https://github.com/syntax-tree/mdast#text) | ```markdown Anything! ``` | [`text`](https://github.com/syntax-tree/hast#text) |
```html
Anything! ``` |
|
| [`table`](https://github.com/syntax-tree/mdast#table), [`tableRow`](https://github.com/syntax-tree/mdast#tablerow), [`tableCell`](https://github.com/syntax-tree/mdast#tablecell) | ```markdown | Pipes | | ----- | ``` | [`element`](https://github.com/syntax-tree/hast#element) (`table`, `thead`, `tbody`, `tr`, `td`, `th`) |
```html
|
|
| [`thematicBreak`](https://github.com/syntax-tree/mdast#thematicbreak) | ```markdown Three asterisks for a thematic break: *** ``` | [`element`](https://github.com/syntax-tree/hast#element) (`hr`) |
```html
Three asterisks for a thematic break: ``` |
|
| `toml` (frontmatter) | ```markdown +++ fenced = true +++ ``` | Nothing | n/a | |
| [`yaml`](https://github.com/syntax-tree/mdast#yaml) (frontmatter) | ```markdown --- fenced: yes --- ``` | Nothing | n/a |
