Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/syntax-tree/mdast-util-to-hast

utility to transform mdast to hast
https://github.com/syntax-tree/mdast-util-to-hast

hast hast-util html markdown mdast mdast-util syntax-tree unist

Last synced: 20 days ago
JSON representation

utility to transform mdast to hast

Lists

README 

        
# mdast-util-to-hast



[![Build][build-badge]][build]

[![Coverage][coverage-badge]][coverage]

[![Downloads][downloads-badge]][downloads]

[![Size][size-badge]][size]

[![Sponsors][sponsors-badge]][collective]

[![Backers][backers-badge]][collective]

[![Chat][chat-badge]][chat]



[mdast][] utility to transform to [hast][].



## Contents



*   [What is this?](#what-is-this)

*   [When should I use this?](#when-should-i-use-this)

*   [Install](#install)

*   [Use](#use)

*   [API](#api)

    *   [`defaultFootnoteBackContent(referenceIndex, rereferenceIndex)`](#defaultfootnotebackcontentreferenceindex-rereferenceindex)

    *   [`defaultFootnoteBackLabel(referenceIndex, rereferenceIndex)`](#defaultfootnotebacklabelreferenceindex-rereferenceindex)

    *   [`defaultHandlers`](#defaulthandlers)

    *   [`toHast(tree[, options])`](#tohasttree-options)

    *   [`FootnoteBackContentTemplate`](#footnotebackcontenttemplate)

    *   [`FootnoteBackLabelTemplate`](#footnotebacklabeltemplate)

    *   [`Handler`](#handler)

    *   [`Handlers`](#handlers)

    *   [`Options`](#options)

    *   [`Raw`](#raw)

    *   [`State`](#state)

*   [Examples](#examples)

    *   [Example: supporting HTML in markdown naïvely](#example-supporting-html-in-markdown-naïvely)

    *   [Example: supporting HTML in markdown properly](#example-supporting-html-in-markdown-properly)

    *   [Example: footnotes in languages other than English](#example-footnotes-in-languages-other-than-english)

    *   [Example: supporting custom nodes](#example-supporting-custom-nodes)

*   [Algorithm](#algorithm)

    *   [Default handling](#default-handling)

    *   [Fields on nodes](#fields-on-nodes)

*   [CSS](#css)

*   [Syntax tree](#syntax-tree)

    *   [Nodes](#nodes)

*   [Types](#types)

*   [Compatibility](#compatibility)

*   [Security](#security)

*   [Related](#related)

*   [Contribute](#contribute)

*   [License](#license)



## What is this?



This package is a utility that takes an [mdast][] (markdown) syntax tree as

input and turns it into a [hast][] (HTML) syntax tree.



## When should I use this?



This project is useful when you want to deal with ASTs and turn markdown to

HTML.



The hast utility [`hast-util-to-mdast`][hast-util-to-mdast] does the inverse of

this utility.

It turns HTML into markdown.



The remark plugin [`remark-rehype`][remark-rehype] wraps this utility to also

turn markdown to HTML at a higher-level (easier) abstraction.



## Install



This package is [ESM only][esm].

In Node.js (version 16+), install with [npm][]:



```sh

npm install mdast-util-to-hast

```



In Deno with [`esm.sh`][esmsh]:



```js

import {toHast} from 'https://esm.sh/mdast-util-to-hast@13'

```



In browsers with [`esm.sh`][esmsh]:



```html



  import {toHast} from 'https://esm.sh/mdast-util-to-hast@13?bundle'



```



## Use



Say we have the following `example.md`:



```markdown

## Hello **World**!

```



…and next to it a module `example.js`:



```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:



```html

Hello World!


```



## API



This package exports the identifiers

[`defaultFootnoteBackContent`][api-default-footnote-back-content],

[`defaultFootnoteBackLabel`][api-default-footnote-back-label],

[`defaultHandlers`][api-default-handlers], and

[`toHast`][api-to-hast].

There is no default export.



### `defaultFootnoteBackContent(referenceIndex, rereferenceIndex)`



Generate the default content that GitHub uses on backreferences.



###### 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 (`Array`).



### `defaultFootnoteBackLabel(referenceIndex, rereferenceIndex)`



Generate the default label that GitHub uses on backreferences.



###### 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



Label (`string`).



### `defaultHandlers`



Default handlers for nodes ([`Handlers`][api-handlers]).



### `toHast(tree[, options])`



Transform mdast to hast.



###### Parameters



*   `tree` ([`MdastNode`][mdast-node])

    — mdast tree

*   `options` ([`Options`][api-options], optional)

    — configuration



###### Returns



hast tree ([`HastNode`][hast-node]).



##### Notes



###### HTML



Raw HTML is available in mdast as [`html`][mdast-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`][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 authors

*   [`hast-util-raw`][hast-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 content



###### Footnotes



Many 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`][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`.



###### Clobbering



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:



```html



alert(x) // `x` now refers to the DOM `p#x` element

```



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`][clobber-example].



###### Unknown nodes



Unknown nodes are nodes with a type that isn’t in `handlers` or `passThrough`.

The default behavior for unknown nodes is:



*   when the node has a `value` (and doesn’t have `data.hName`,

    `data.hProperties`, or `data.hChildren`, see later), create a hast `text`

    node

*   otherwise, create a `
` 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

It works! 


```



> ⚠️ **Danger**: observe that the XSS attack through the `onerror` attribute

> is still present.



### Example: supporting HTML in markdown properly



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`][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`):



```js

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 works! '

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

It works! 


```



> 👉 **Note**: observe that the XSS attack through the `onerror` attribute

> is no longer present.



### Example: footnotes in languages other than English



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:



```js

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:



```html

Bonjour1


Footnotes


    

  1. 

    Monde! ↩
    

    2. 




```



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:



```diff

@@ -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:



```diff

@@ -1,8 +1,8 @@

 
Bonjour1


-
Footnotes


+
Notes de bas de page


 
    

     
  1. 

    -
    Monde! ↩
    

    +
    Monde! ↩
    

     
    2. 

     


 

```



### Example: supporting custom nodes



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 `` element in HTML, we can use a handler:



```js

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:



```js

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)))

```



## Algorithm



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.



### Default handling



The following table gives insight into what input turns into what output:



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



A greater than…




```



[`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


before a line break…


```



[`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

backtick.fences('for blocks')



```



[`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 tildes for delete.


```



[`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

![Alt text](/logo.png "title")

```



[`element`](https://github.com/syntax-tree/hast#element) (`img`)



```html

Alt text


```



[`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

Alt text


```



[`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 backticks for inline code.


```



[`link`](https://github.com/syntax-tree/mdast#link)



```markdown

[Example](https://example.com "title")

```



[`element`](https://github.com/syntax-tree/hast#element) (`a`)



```html

Example


```



[`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

Example


```



[`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

    

  • asterisks for unordered items
    • 



    

  1. decimals and a dot for ordered items
    2. 



```



[`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



Pipes



```



[`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



> 👉 **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

alert(1)

```



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



alert(3)

```



Yields:



```html

Hello


```



Passing `allowDangerousHtml: true` to `mdast-util-to-hast` is typically still

not enough to run unsafe code:



```html

Hello


<script>alert(3)</script>

```



If `allowDangerousHtml: true` is also given to `hast-util-to-html` (or

`rehype-stringify`), the unsafe code runs:



```html

Hello


alert(3)

```



Use [`hast-util-sanitize`][hast-util-sanitize] to make the hast tree safe.



## Related



*   [`hast-util-to-mdast`](https://github.com/syntax-tree/hast-util-to-mdast)

    — transform hast to mdast

*   [`hast-util-to-xast`](https://github.com/syntax-tree/hast-util-to-xast)

    — transform hast to xast

*   [`hast-util-sanitize`](https://github.com/syntax-tree/hast-util-sanitize)

    — sanitize hast nodes



## Contribute



See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get

started.

See [`support.md`][support] for ways to get help.



This project has a [code of conduct][coc].

By interacting with this repository, organization, or community you agree to

abide by its terms.



## License



[MIT][license] © [Titus Wormer][author]



[build-badge]: https://github.com/syntax-tree/mdast-util-to-hast/workflows/main/badge.svg



[build]: https://github.com/syntax-tree/mdast-util-to-hast/actions



[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-to-hast.svg



[coverage]: https://codecov.io/github/syntax-tree/mdast-util-to-hast



[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-to-hast.svg



[downloads]: https://www.npmjs.com/package/mdast-util-to-hast



[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-to-hast



[size]: https://bundlejs.com/?q=mdast-util-to-hast



[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg



[backers-badge]: https://opencollective.com/unified/backers/badge.svg



[collective]: https://opencollective.com/unified



[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg



[chat]: https://github.com/syntax-tree/unist/discussions



[npm]: https://docs.npmjs.com/cli/install



[license]: license



[author]: https://wooorm.com



[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c



[esmsh]: https://esm.sh



[typescript]: https://www.typescriptlang.org



[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md



[support]: https://github.com/syntax-tree/.github/blob/main/support.md



[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md



[mdast]: https://github.com/syntax-tree/mdast



[mdast-node]: https://github.com/syntax-tree/mdast#nodes



[mdast-html]: https://github.com/syntax-tree/mdast#html



[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm



[hast]: https://github.com/syntax-tree/hast



[hast-node]: https://github.com/syntax-tree/hast#nodes



[properties]: https://github.com/syntax-tree/hast#properties



[hast-util-table-cell-style]: https://github.com/mapbox/hast-util-table-cell-style



[hast-util-to-mdast]: https://github.com/syntax-tree/hast-util-to-mdast



[hast-util-to-html]: https://github.com/syntax-tree/hast-util-to-html



[hast-util-raw]: https://github.com/syntax-tree/hast-util-raw



[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize



[remark-rehype]: https://github.com/remarkjs/remark-rehype



[vfile]: https://github.com/vfile/vfile



[clobber-example]: https://github.com/rehypejs/rehype-sanitize#example-headings-dom-clobbering



[github-markdown-css]: https://github.com/sindresorhus/github-markdown-css



[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting



[dfn-literal]: https://github.com/syntax-tree/hast#literal



[api-default-footnote-back-content]: #defaultfootnotebackcontentreferenceindex-rereferenceindex



[api-default-footnote-back-label]: #defaultfootnotebacklabelreferenceindex-rereferenceindex



[api-default-handlers]: #defaulthandlers



[api-footnote-back-content-template]: #footnotebackcontenttemplate



[api-footnote-back-label-template]: #footnotebacklabeltemplate



[api-handler]: #handler



[api-handlers]: #handlers



[api-options]: #options



[api-raw]: #raw



[api-state]: #state



[api-to-hast]: #tohasttree-options