Package Exports
- remark-html
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (remark-html) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
remark-html
Compile markdown to HTML with remark.
⚠️ 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.
Installation
npm:
npm install remark-html
Usage
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])
options
All options except for sanitize
are passed to
hast-util-to-html
.
options.sanitize
How to sanitise the output (Object
or boolean
, default: false
).
If false
, no HTML is sanitized, and dangerous HTML is left unescaped.
If true
or an object
, sanitation is done by hast-util-sanitize
If an object is passed in, it’s given as a schema to hast-util-sanitize
.
If true
, input is sanitised according to GitHub’s sanitation rules.
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(/* ... */)
CommonMark
You still need to set
commonmark: true
inremark-parse
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 importance) 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.
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 attributes 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>
Contribute
See contributing.md
in remarkjs/remark
for ways to get
started.
This organisation has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.