mdast-html
mdast-html compiles markdown to HTML. Built on mdast, an extensively tested and pluggable parser.
Installation
npm:
npm install mdast-html
mdast-html is also available for bower, component, and duo, and as an AMD, CommonJS, and globals module, uncompressed and compressed.
Table of Contents
Command line
Use mdast-html together with mdast:
npm install --global mdast mdast-html
Let’s say example.md
looks as follows:
# Hello & World
**Alpha**, _bravo_, and ~~Charlie~~.
Then, run mdast-html on example.md
:
mdast -u mdast-html example.md -o
Yields (check out the newly created example.html
file):
<h1>Hello & World</h1>
<p><strong>Alpha</strong>, <em>bravo</em>, and <del>Charlie</del>.</p>
Programmatic
mdast.use(html, options)
Parameters
html
— This plugin;options
(Object?
) — See below.
Let’s say example.js
looks as follows:
var mdast = require('mdast');
var html = require('mdast-html');
var doc = '# Hello & World\n' +
'\n' +
'**Alpha**, _bravo_, and ~~Charlie~~.\n';
var result = mdast().use(html).process(doc);
console.log(result);
/*
* '<h1>Hello & 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 asimg
) with a slash; -
sanitize
(boolean
, default:false
) — Whether or not to allow the use of HTML inside markdown.
These can passed to mdast.use()
as a second argument, or on the CLI:
mdast --use 'html=sanitize:false,xhtml:false,entities:"escape"' example.md
You can define these in .mdastrc
or package.json
files
too. An example .mdastrc
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 mdast-html.
The object at settings
determines how mdast parses markdown code.
Read more about the latter on mdast’s readme.
CommonMark
You still need to set
commonmark: true
in mdast’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
mdast-html works great with:
-
mdast-toc, which generates tables of contents;
-
mdast-github, which generates references to GitHub issues, PRs, users, and more;
-
mdast-comment-config and mdast-yaml-config, which specify how HTML is compiled in the document itself;
-
...and more.
All mdast nodes
can be compiled to HTML. In addition, mdast-html can be told how to
compile markdown nodes through three data
properties:
htmlName
— Tag-name to compile as;htmlContent
— HTML content to add (instead ofchildren
andvalue
);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>