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

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

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 module, example.js, looks as follows:

import fs from 'node:fs'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkHtml from 'remark-html'

const buf = fs.readFileSync('example.md')

unified()
  .use(remarkParse)
  .use(remarkHtml)
  .process(buf)
  .then((file) => {
    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

This package exports no identifiers. The default export is remarkHtml.

unified().use(remarkHtml[, options])

Serialize Markdown as HTML.

options

All options except for sanitize and handlers are passed to hast-util-to-html.

The underlying tools allow much more customisation. It is recommended to replace this project with remark-rehype and rehype-stringify ;

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 a schema for 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 other plugins 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(/* … */)

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