remarkjs / Remark Html
Programming Languages
Projects that are alternatives of or similar to Remark Html
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 = 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 persists -
true
— HTML is sanitized according to GitHub’s sanitation rules, dangerous HTML is dropped -
Object
— 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 = 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 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 - …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 as -
hChildren
— 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.