remark-html

Compile markdown to HTML with remark.

Installation

npm:

npm install remark-html

Usage

var remark = require('remark');
var html = require('remark-html');

var file = remark().use(html).process([
  '# Hello & World',
  '',
  '**Alpha**, _bravo_, and ~~Charlie~~.'
].join('\n'));

console.log(String(file));

Yields:

<h1>Hello &#x26; World</h1>
<p><strong>Alpha</strong>, <em>bravo</em>, and <del>Charlie</del>.</p>

API

remark.use(html[, options])

options

All options except for sanitize are passed to hast-util-to-html.

options.sanitize

How to sanitise the output (Object or boolean, default: false).

If true or an object, sanitation is done by hast-util-sanitize. If an object is passed in, it’s given as a schema to sanitize. If true, input is sanitised according to GitHub’s sanitation rules.

For example, to add strict sanitation but allowing classNames, use something like:

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

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

remark().use(html, {sanitize: schema}).process(/*...*/);

CommonMark

You still need to set commonmark: true in remarks options.

CommonMark support is a goal but not (yet) a necessity. There are some (roughly 115 of 550, relating to inline precedence, lists, emphasis and importance) issues which I’d like to cover in the future. Note that this sounds like a lot, but they have to do with obscure differences which do not often occur in the real world. Read more on some of the reasoning in doc/commonmark.md.

Integrations

remark-html works great with:

• wooorm/remark-toc, which generates tables of contents;
• wooorm/remark-github, which generates references to GitHub issues, PRs, users, and more;
• ...and more.

All MDAST nodes can be compiled to HTML. Unknown MDAST nodes are compiled to div nodes.

In addition, remark-html can be told how to compile nodes through three data properties (more information):

• hName — Tag-name to compile as;
• hChildren — HTML content to add (instead of children and value);
• hProperties — Map of attributes to add.

For example, the following node:

{
  type: 'emphasis',
  data: {
    hName: 'i',
    hProperties: {
      className: 'foo'
    },
    hChildren: [{
        type: 'text',
        value: 'bar'
    }]
  },
  children: [{
    type: 'text',
    value: 'baz',
  }]
}

...would yield:

<i class="foo">bar</i>

License

MIT © Titus Wormer