remark-html

What is remark-html?

The remark-html package is a plugin for the remark processor that allows you to convert Markdown content into HTML. It is part of the unified collective, which provides a suite of tools for processing and transforming content.

What are remark-html's main functionalities?

Convert Markdown to HTML

This feature allows you to convert Markdown content into HTML. The code sample demonstrates how to use the remark processor with the remark-html plugin to transform a Markdown string into HTML.

const remark = require('remark');
const html = require('remark-html');

remark()
  .use(html)
  .process('# Hello World!', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Customizing HTML Output

This feature allows you to customize the HTML output. In this example, the `sanitize` option is set to `false`, which means that HTML tags in the Markdown content will not be sanitized and will be included in the output.

const remark = require('remark');
const html = require('remark-html');

remark()
  .use(html, { sanitize: false })
  .process('# Hello <em>World</em>!', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Other packages similar to remark-html

markdown-it

markdown-it is a fast and flexible Markdown parser that can be extended with plugins. It provides similar functionality to remark-html by converting Markdown to HTML, but it is known for its speed and extensibility.

marked

marked is a low-level Markdown compiler that allows for fast and efficient conversion of Markdown to HTML. It is similar to remark-html in its core functionality but is designed to be a simple and fast solution.

showdown

showdown is a bidirectional Markdown to HTML converter written in JavaScript. It offers similar functionality to remark-html but also supports converting HTML back to Markdown, providing more flexibility in content transformation.

README

remark-html

remark plugin to serialize Markdown as HTML.

⚠️ This package essentially packs remark-rehype and rehype-stringify, and although it does support some customisation, it isn’t very pluggable. It’s probably smarter to use remark-rehype directly and benefit from the rehype ecosystem.

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 &#x26; 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 are passed to hast-util-to-html.

options.sanitize

How to sanitize the output (Object or boolean, default: true).

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 sanitized 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 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(/* … */)

CommonMark

You still need to set commonmark: true in remark-parses 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 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 of children and 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:

<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.

License

MIT © Titus Wormer