unified

Project: rehypejs/rehype

Package: rehype-stringify@9.0.3

  1. rehype plugin to serialize HTML
  1. unified 179
  2. plugin 136
  3. html 123
  4. rehype 91
  5. rehype-plugin 61
  6. tree 44
  7. ast 37
  8. syntax 28
  9. stringify 18
  10. compile 13
  11. serialize 12
  12. abstract 10

rehype-stringify

Build Coverage Downloads Size Sponsors Backers Chat

rehype plugin to add support for serializing to HTML.

Contents

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 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, which combines unified, 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 instead.

If you don’t use plugins and have access to a syntax tree, you can directly use 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, improves the readability of HTML source code as it adds insignificant but pretty whitespace between elements. There is also the preset rehype-minify for when you want the inverse: minified and mangled HTML.

Install

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

npm install rehype-stringify

In Deno with esm.sh:

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

In browsers with esm.sh:

<script type="module">
  import rehypeStringify from 'https://esm.sh/rehype-stringify@10?bundle'
</script>

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.

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

Plugin to add support for serializing to HTML.

Parameters
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

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 to serialize XML.

Fields

Syntax

HTML is serialized according to WHATWG HTML (the living standard), which is also followed by all browsers.

Syntax tree

The syntax tree format used in rehype is hast.

Types

This package is fully typed with TypeScript. It exports the additional types CharacterReferences and Options.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, rehype-stringify@^10, compatible with Node.js 16.

Security

As rehype works on HTML, and improper use of HTML can open you up to a cross-site scripting (XSS) attack, use of rehype can also be unsafe. Use rehype-sanitize to make the tree safe.

Use of rehype plugins could also open you up to other attacks. Carefully assess each plugin and the risks involved in using them.

For info on how to submit a report, see our security policy.

Contribute

See contributing.md in rehypejs/.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.

Support this effort and give back by sponsoring on OpenCollective!

Vercel

Motif

HashiCorp

GitBook

Gatsby

Netlify

Coinbase

ThemeIsle

Expo

Boost Note

Markdown Space

Holloway


You?

License

MIT © Titus Wormer