# 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?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`unified().use(rehypeStringify[, options])`](#unifieduserehypestringify-options)
* [`CharacterReferences`](#characterreferences)
* [`Options`](#options)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#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][]:
```sh
npm install rehype-stringify
```
In Deno with [`esm.sh`][esmsh]:
```js
import rehypeStringify from 'https://esm.sh/rehype-stringify@10'
```
In browsers with [`esm.sh`][esmsh]:
```html
```
## Use
Say we have the following module `example.js`:
```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:
```html
Hi
Hello, world!
```
## 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: `` instead of ``;
see `tightSelfClosing` to control whether a space is used before the slash;
not used in the HTML space
* `closeSelfClosing` (`boolean`, default: `false`)
— close self-closing nodes with an extra slash (`/`): `` instead of
``; see `tightSelfClosing` to control whether a space is used before
the slash; not used in the SVG space.
* `collapseEmptyAttributes` (`boolean`, default: `false`)
— collapse empty attributes: get `class` instead of `class=""`; not used in
the SVG space; boolean attributes (such as `hidden`) are always collapsed
* `omitOptionalTags` (`boolean`, default: `false`)
— omit optional opening and closing tags; to illustrate, in
`
one
two
`, both `` closing tags can be
omitted, the first because it’s followed by another `li`, the last because
it’s followed by nothing; not used in the SVG space
* `preferUnquoted` (`boolean`, default: `false`)
— leave attributes unquoted if that results in less bytes; not used in the
SVG space
* `quote` (`'"'` or `"'"`, default: `'"'`)
— preferred quote to use
* `quoteSmart` (`boolean`, default: `false`)
— use the other quote if that results in less bytes
* `space` (`'html'` or `'svg'`, default: `'html'`)
— which space the document is in; when an `