remark-html
remark plugin to serialize Markdown as HTML.
⚠️ This package essentially packs
remark-rehype
andrehype-stringify
, and although it does support some customisation, it isn’t very pluggable. It’s probably smarter to useremark-rehype
directly 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 = var unified = var markdown = var html =
Now, running node example
yields:
Hello & WorldA block quote.Some emphasis, importance, and code.
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 aschema
for 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 className
s, use something
like:
// ...var merge = var github = var schema =
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 ofchildren
andvalue
), inhast
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:
<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.