JarCastingremark-html
remark plugin to serialize Markdown as HTML.
⚠️ This package essentially packsremark-rehypeandrehype-stringify, and although it does support some customisation, it isn’t very pluggable. It’s probably smarter to useremark-rehypedirectly and benefit from the rehype ecosystem.
Note!
This plugin is ready for the new parser in remark (remarkjs/remark#536). The current and previous version of the plugin works with the current and previous version of remark.
Install
npm:
npm install remark-html
Use
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 & 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])
Serialize Markdown as HTML.
options
All options except for sanitize and handlers are passed to hast-util-to-html.
options.handlers
Object mapping mdast nodes to functions handling them. This option is passed to mdast-util-to-hast.
options.sanitize
How to sanitize the output (Object or boolean, default: true):
false— HTML is not sanitized, dangerous HTML persiststrue— HTML is sanitized according to GitHub’s sanitation rules, dangerous HTML is droppedObject— the object is treated as aschemafor how to sanitize withhast-util-sanitize, dangerous HTML is dropped
Note that raw HTML in Markdown cannot be sanitized, so it’s removed. A schema can still be used to allow certain values from integrations though. To support HTML in Markdown, use
rehype-raw.
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(/* … */)
Integrations
remark-html works great with:
remark-autolink-headings— Automatically add links to headings in Markdownremark-github— Generate references to GitHub issues, PRs, users, and moreremark-highlight.js— Highlight code blocksremark-html-emoji-image— Transform emoji unicodes into html imagesremark-html-katex— Transform math to HTML with KaTeXremark-math— Math support for Markdown (inline and block)remark-midas— Highlight CSS code with midasremark-toc— Generate a Tables of Contents- …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 ashChildren— HTML content to add (instead ofchildrenandvalue), inhasthProperties— Map of properties 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>
Security
Use of remark-html is unsafe by default and opens you up to a cross-site scripting (XSS) attack. Pass sanitize: true to prevent attacks. Settings sanitize to anything else may be unsafe.
Contribute
See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
