Narcissistic Preening Monarch

    mdast-util-to-hast
    TypeScript icon, indicating that this package has built-in type declarations

    12.1.0 • Public • Published

    mdast-util-to-hast

    Build Coverage Downloads Size Sponsors Backers Chat

    mdast utility to transform to hast.

    Note: You probably want to use remark-rehype.

    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-to-hast

    Use

    Say we have the following example.md:

    ## Hello **World**!

    …and next to it, example.js:

    import fs from 'node:fs'
    import {fromMarkdown} from 'mdast-util-from-markdown'
    import {toHast} from 'mdast-util-to-hast'
    import {toHtml} from 'hast-util-to-html'
    
    const mdast = fromMarkdown(fs.readFileSync('example.md'))
    const hast = toHast(mdast)
    const html = toHtml(hast)
    
    console.log(html)

    Which when running with node example yields:

    <h2>Hello <strong>World</strong>!</h2>

    API

    This package exports the following identifiers: toHast, defaultHandlers, all, one There is no default export.

    toHast(node[, options])

    Transform the given mdast tree to a hast tree.

    Options
    options.allowDangerousHtml

    Whether to allow html nodes and inject them as raw HTML (boolean, default: false). Only do this when using hast-util-to-html (rehype-stringify) or hast-util-raw (rehype-raw) later: raw nodes are not a standard part of hast.

    options.clobberPrefix

    Prefix to use before the id attribute on footnotes to prevent it from clobbering (string, default: 'user-content-'). DOM clobbering is this:

    <p id=x></p>
    <script>alert(x)</script>

    Elements by their ID are made available in browsers on the window object. Using a prefix this that from being a problem.

    options.footnoteLabel

    Label to use for the footnotes section (string, default: 'Footnotes'). Affects screen reader users. Change it if you’re authoring in a different language.

    options.footnoteBackLabel

    Label to use from backreferences back to their footnote call (string, default: 'Back to content'). Affects screen reader users. Change it if you’re authoring in a different language.

    options.handlers

    Object mapping mdast nodes to functions handling them. Take a look at lib/handlers/ for examples.

    options.passThrough

    List of custom mdast node types to pass through (keep) in hast (Array.<string>, default: []). If the passed through nodes have children, those children are expected to be mdast and will be handled.

    options.unknownHandler

    Handler for unknown nodes (that aren’t in handlers or passThrough).

    Default behavior:

    • Unknown nodes with children are transformed to div elements
    • Unknown nodes with value are transformed to text nodes
    Returns

    HastNode.

    Notes
    Examples
    hName

    node.data.hName sets the tag name of an element. The following mdast:

    {
      type: 'strong',
      data: {hName: 'b'},
      children: [{type: 'text', value: 'Alpha'}]
    }

    Yields, in hast:

    {
      type: 'element',
      tagName: 'b',
      properties: {},
      children: [{type: 'text', value: 'Alpha'}]
    }
    hProperties

    node.data.hProperties in sets the properties of an element. The following mdast:

    {
      type: 'image',
      src: 'circle.svg',
      alt: 'Big red circle on a black background',
      title: null,
      data: {hProperties: {className: ['responsive']}}
    }

    Yields, in hast:

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

    {
      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, in hast (note: the pre and language-js class are normal mdast-util-to-hast functionality):

    {
      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: ';'}
        ]
      }]
    }

    defaultHandlers

    Object mapping mdast node types to functions that can handle them. See lib/handlers/index.js.

    all(h, parent)

    Helper function for writing custom handlers passed to options.handlers. Pass it h and a parent node (mdast) and it will turn the node’s children into an array of transformed nodes (hast).

    one(h, node, parent)

    Helper function for writing custom handlers passed to options.handlers. Pass it h, a node, and its parent (mdast) and it will turn node into hast content.

    Recommended CSS

    The following CSS is needed to make footnotes look a bit like GitHub. For the complete actual CSS that GitHub uses see sindresorhus/github-markdown-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: ']';
    }

    Security

    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:

    var 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.

    var 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>
    &#x3C;script>alert(3)&#x3C;/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.

    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

    Install

    npm i mdast-util-to-hast

    DownloadsWeekly Downloads

    3,562,036

    Version

    12.1.0

    License

    MIT

    Unpacked Size

    64.6 kB

    Total Files

    62

    Last publish

    Collaborators

    • wooorm
    • kmck