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 if they have children or text nodes if they have value.

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