remark-vdom

remark plugin to compile Markdown to Virtual DOM.

• Inherently safe and sanitized: there is no way to pass raw HTML through
• Supports footnotes, todo lists
• Support VNode keys
• Custom components overwriting default elements (MyLink instead of <a>)

Note!

This plugin is ready for the new parser in remark (micromark, see remarkjs/remark#536). No change is needed: it works exactly the same now as it did before!

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install remark-vdom

Use

Say we have the following file, example.js:

import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkVdom from 'remark-vdom'

unified()
  .use(remarkParse)
  .use(remarkVdom)
  .process('Some _emphasis_, **importance**, and `code`.')
  .then((file) => {
    console.dir(file.result, {depth: null})
  })

Now, running node example yields:

VirtualNode {
  tagName: 'DIV',
  properties: { key: undefined },
  children: [
    VirtualNode {
      tagName: 'P',
      properties: { key: undefined },
      children: [
        VirtualText { text: 'Some ' },
        VirtualNode {
          tagName: 'EM',
          properties: { key: undefined },
          children: [ VirtualText { text: 'emphasis' } ],
          key: 'h-3',
          namespace: null,
          count: 1,
          hasWidgets: false,
          hasThunks: false,
          hooks: undefined,
          descendantHooks: false
        },
        VirtualText { text: ', ' },
        VirtualNode {
          tagName: 'STRONG',
          properties: { key: undefined },
          children: [ VirtualText { text: 'importance' } ],
          key: 'h-4',
          namespace: null,
          count: 1,
          hasWidgets: false,
          hasThunks: false,
          hooks: undefined,
          descendantHooks: false
        },
        VirtualText { text: ', and ' },
        VirtualNode {
          tagName: 'CODE',
          properties: { key: undefined },
          children: [ VirtualText { text: 'code' } ],
          key: 'h-5',
          namespace: null,
          count: 1,
          hasWidgets: false,
          hasThunks: false,
          hooks: undefined,
          descendantHooks: false
        },
        VirtualText { text: '.' }
      ],
      key: 'h-2',
      namespace: null,
      count: 10,
      hasWidgets: false,
      hasThunks: false,
      hooks: undefined,
      descendantHooks: false
    }
  ],
  key: 'h-1',
  namespace: null,
  count: 11,
  hasWidgets: false,
  hasThunks: false,
  hooks: undefined,
  descendantHooks: false
}

API

This package exports no identifiers. The default export is remarkVdom.

unified().use(remarkVdom[, options])

Compile Markdown to Virtual DOM.

ℹ️ In unified@9.0.0, the result of .process changed from file.contents to file.result.

options

options.sanitize

How to sanitize the output (Object or boolean, default: null).

Sanitation is done by hast-util-sanitize, except when false is given. If an object is passed in, it’s given as a schema to sanitize. By default, input is sanitized according to GitHub’s sanitation rules.

Embedded HTML is always stripped.

For example, by default classNames are stripped. To keep them in, use something like:

var merge = require('deepmerge')
var gh = require('hast-util-sanitize/lib/github')

var schema = merge(gh, {attributes: {'*': ['className']}})

var vtree = remark()
  .use(vdom, {sanitize: schema})
  .processSync(/* ... */)

options.prefix

Optimization hint (string, default: h-).

options.h

Hyperscript to use (Function, default: require('virtual-dom/h')).

options.components

Map of tag names to custom components (Object.<Function>, optional). That component is invoked with tagName, props, and children. It can return any VDOM compatible value (such as VNode, VText, Widget). For example:

var components = {code: code}

function code(tagName, props, children) {
  // Ensure a default programming language is set.
  if (!props.className) {
    props.className = 'language-js'
  }

  return h(tagName, props, children)
}

Integrations

Integrates with the same tools as remark-html.

Security

Use of remark-vdom is safe by default, but changing the sanitize option can open you up to a cross-site scripting (XSS) attack if the tree is unsafe.

Related

• remark-rehype — Properly transform to an HTML virtual DOM (hast)
• rehype-react — Transform hast to React
• remark-react — Compile markdown to React
• remark-man — Compile to man pages
• remark-html — Compile to HTML

Contribute

See contributing.md in remarkjs/.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