rehype-stringify

[![Build][build-badge]][build] [![Coverage][coverage-badge]][coverage] [![Downloads][downloads-badge]][downloads] [![Size][size-badge]][size] [![Sponsors][sponsors-badge]][collective] [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat]

[rehype][] plugin to add support for serializing to HTML.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • unified().use(rehypeStringify[, options])
  • CharacterReferences
  • Options
• Syntax
• Syntax tree
• Types
• Compatibility
• Security
• Contribute
• Sponsor
• License

What is this?

This package is a [unified][] ([rehype][]) plugin that defines how to take a syntax tree as input and turn it into serialized HTML. When it’s used, HTML is serialized as the final result.

See [the monorepo readme][rehype] for info on what the rehype ecosystem is.

When should I use this?

This plugin adds support to unified for serializing HTML. If you also need to parse HTML, you can alternatively use [rehype][rehype-core], which combines unified, [rehype-parse][rehype-parse], and this plugin.

When you are in a browser, trust your content, don’t need formatting options, and value a smaller bundle size, you can use [rehype-dom-stringify][rehype-dom-stringify] instead.

If you don’t use plugins and have access to a syntax tree, you can directly use [hast-util-to-html][hast-util-to-html], which is used inside this plugin. rehype focusses on making it easier to transform content by abstracting such internals away.

A different plugin, [rehype-format][rehype-format], improves the readability of HTML source code as it adds insignificant but pretty whitespace between elements. There is also the preset [rehype-minify][rehype-minify] for when you want the inverse: minified and mangled HTML.

Install

This package is [ESM only][esm]. In Node.js (version 16+), install with [npm][]:

npm install rehype-stringify

In Deno with [esm.sh][esmsh]:

import rehypeStringify from 'https://esm.sh/rehype-stringify@10'

In browsers with [esm.sh][esmsh]:

Use

Say we have the following module example.js:

import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import remarkGfm from 'remark-gfm'
import remarkParse from 'remark-parse'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('# Hi\n\n*Hello*, world!')

console.log(String(file))

…running that with node example.js yields:

<h1>Hi</h1>
<p><em>Hello</em>, world!</p>

API

This package exports no identifiers. The default export is [rehypeStringify][api-rehype-stringify].

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

Plugin to add support for serializing to HTML.

Parameters

• options ([Options][api-options], optional) — configuration

Returns

Nothing (undefined).

CharacterReferences

How to serialize character references (TypeScript type).

> ⚠️ Note: omitOptionalSemicolons creates what HTML calls “parse errors” > but is otherwise still valid HTML — don’t use this except when building a > minifier. > Omitting semicolons is possible for certain named and numeric references in > some cases.

> ⚠️ Note: useNamedReferences can be omitted when using > useShortestReferences.

Fields

• useNamedReferences (boolean, default: false) — prefer named character references (&) where possible
• omitOptionalSemicolons (boolean, default: false) — whether to omit semicolons when possible
• useShortestReferences (boolean, default: false) — prefer the shortest possible reference, if that results in less bytes

Options

Configuration (TypeScript type).

> ⚠️ Danger: only set allowDangerousCharacters and allowDangerousHtml if > you completely trust the content.

> 👉 Note: allowParseErrors, bogusComments, tightAttributes, and > tightDoctype > intentionally create parse errors in markup (how parse errors are handled is > well defined, so this works but isn’t pretty).

> 👉 Note: this is not an XML serializer. > It supports SVG as embedded in HTML. > It does not support the features available in XML. > Use [xast-util-to-xml][xast-util-to-xml] to serialize XML.

Fields

• allowDangerousCharacters (boolean, default: false) — do not encode some characters which cause XSS vulnerabilities in older browsers
• allowDangerousHtml (boolean, default: false) — allow [Raw][raw] nodes and insert them as raw HTML; when false, Raw nodes are encoded
• allowParseErrors (boolean, default: false) — do not encode characters which cause parse errors (even though they work), to save bytes; not used in the SVG space.
• bogusComments (boolean, default: false) — use “bogus comments” instead of comments to save byes: instead of
• characterReferences ([CharacterReferences][api-character-references], optional) — configure how to serialize character references
• closeEmptyElements (boolean, default: false) — close SVG elements without any content with slash (/) on the opening tag instead of an end tag: `