JavaScript HTML
Clone or download

readme.md

remark-html Build Status Coverage Status Chat

Compile markdown to HTML with remark.

⚠️ This package essentially packs remark-rehype and rehype-stringify, and although it does support some customisation, it isn’t very pluggable. It’s probably smarter to use remark-rehype directly and benefit from the rehype ecosystem.

Installation

npm:

npm install remark-html

Usage

Say we have the following file, example.md:

# Hello & World

> A block quote.

* Some _emphasis_, **importance**, and `code`.

And our script, example.js, looks as follows:

var fs = require('fs');
var unified = require('unified');
var markdown = require('remark-parse');
var html = require('remark-html');

unified()
  .use(markdown)
  .use(html)
  .process(fs.readFileSync('example.md'), function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Now, running node example yields:

<h1>Hello &#x26; World</h1>
<blockquote>
<p>A block quote.</p>
</blockquote>
<ul>
<li>Some <em>emphasis</em>, <strong>importance</strong>, and <code>code</code>.</li>
</ul>

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}).processSync(/*...*/);

CommonMark

You still need to set commonmark: true in remark-parses 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.

Integrations

remark-html works great with:

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), in HAST
  • 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>

Contribute

See contribute.md in remarkjs/remarkj for ways to get started.

This organisation has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.

License

MIT © Titus Wormer