remark-html

remark-html compiles markdown to HTML. Built on remark, an extensively tested and pluggable parser.

Installation

npm:

npm install remark-html

remark-html is also available for duo, and as an AMD, CommonJS, and globals module, uncompressed and compressed.

Table of Contents

• Command line

• Programmatic

  • remark.use(html, options)

• Configuration

• CommonMark

• Integrations

• License

Command line

Use remark-html together with remark:

npm install --global remark remark-html

Let’s say example.md looks as follows:

# Hello & World

**Alpha**, _bravo_, and ~~Charlie~~.

Then, run remark-html on example.md:

remark -u remark-html example.md -o

Yields (check out the newly created example.html file):

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

Programmatic

remark.use(html, options)

Parameters

• html — This plugin;
• options (Object?) — See below.

Let’s say example.js looks as follows:

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

var doc = '# Hello & World\n' +
    '\n' +
    '**Alpha**, _bravo_, and ~~Charlie~~.\n';

var result = remark().use(html).process(doc);

console.log(result);
/*
 * '<h1>Hello &amp; World</h1>\n<p><strong>Alpha</strong>, <em>bravo</em>, and <del>Charlie</del>.</p>'
 */

Configuration

All options, including the options object itself, are optional:

• entities (true, 'numbers', or 'escape', default: true) — How to encode non-ASCII and HTML-escape characters: the default generates named entities (& > &); 'numbers' generates numbered entities (& > &), and 'escape' only encodes characters which are required by HTML to be escaped: &, <, >, ", ', and `, leaving non-ASCII characters untouched.

• xhtml (boolean, default: false) — Whether or not to terminate self-closing tags (such as img) with a slash;

• sanitize (boolean, default: false) — Whether or not to allow the use of HTML inside markdown.

These can passed to remark.use() as a second argument, or on the CLI:

remark --use 'html=sanitize:false,xhtml:false,entities:"escape"' example.md

You can define these in .remarkrc or package.json files too. An example .remarkrc file could look as follows:

{
  "plugins": {
    "html": {
        "sanitize": false,
        "xhtml": false,
        "entities": "numbers"
    }
  },
  "settings": {
    "commonmark": true
  }
}

Where the object at plugins.html are the options for remark-html. The object at settings determines how remark parses markdown code. Read more about the latter on remark’s readme.

CommonMark

You still need to set commonmark: true in remark’s 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 strongness) 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:

• remark-toc, which generates tables of contents;

• remark-github, which generates references to GitHub issues, PRs, users, and more;

• remark-comment-config and remark-yaml-config, which specify how HTML is compiled in the document itself;

• mdast-highlight.js and mdast-midas which highlight code-blocks;

• mdast-autolink-headings, which generates GitHub style anchors for each of the headings;

• ...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:

• htmlName — Tag-name to compile as;
• htmlContent — HTML content to add (instead of children and value);
• htmlAttributes — Map of attributes to add.

For example, the following node:

{
  "type": "emphasis",
  "data": {
    "htmlName": "i",
    "htmlAttributes": {
      "id": "foo"
    },
    "htmlContent": "bar"
  },
  "children": [{
    "type": "text",
    "value": "baz",
  }]
}

...would yield:

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

License

MIT © Titus Wormer