plugin to compile Markdown to HTML
remark plugin to serialize Markdown as HTML.
⚠️ This package essentially packs
remark-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.
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.
npm:
npm install remark-html
Say we have the following file,
example.md:
# Hello & World> A block quote.
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 exampleyields:
Hello & World
A block quote.
code
.remark().use(html[, options])
Serialize Markdown as HTML.
options
All options except for
sanitizeand
handlersare 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 (
Objector
boolean, default:
true):
false— HTML is not sanitized, dangerous HTML persists
true— HTML is sanitized according to GitHub’s sanitation rules, dangerous HTML is dropped
Object— the object is treated as a
schemafor how to sanitize with
hast-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(/* … */)
remark-htmlworks great with:
remark-autolink-headings— Automatically add links to headings in Markdown
remark-github— Generate references to GitHub issues, PRs, users, and more
remark-highlight.js— Highlight code blocks
remark-html-emoji-image— Transform emoji unicodes into html images
remark-html-katex— Transform math to HTML with KaTeX
remark-math— Math support for Markdown (inline and block)
remark-midas— Highlight CSS code with midas
remark-toc— Generate a Tables of Contents
All mdast nodes can be compiled to HTML. Unknown mdast nodes are compiled to
divnodes if they have
childrenor
textnodes if they have
value.
In addition, remark-html can be told how to compile nodes through three
dataproperties (more information):
hName— Tag name to compile as
hChildren— HTML content to add (instead of
childrenand
value), in
hast
hProperties— 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:
bar
Use of
remark-htmlis unsafe by default and opens you up to a cross-site scripting (XSS) attack. Pass
sanitize: trueto prevent attacks. Settings
sanitizeto anything else may be unsafe.
contributing.mdin
remarkjs/.githubfor ways to get started. See
support.mdfor 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.