rehype-stringify
v10.0.1TypeScript
rehype plugin to serialize HTML
0/weekUpdated 1 years agoMITUnpacked: 20.2 KB
Published by Titus Wormer
npm install rehype-stringifyrehype-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])](#unifieduserehypestringify-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][]:
``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\nHello, world!')
console.log(String(file))
`
…running that with node example.js yields:
` Hello, world!html`Hi
API
This package exports no identifiers.
The default export is [rehypeStringify][api-rehype-stringify].
$3
Plugin to add support for serializing to HTML.
###### Parameters
* options ([Options][api-options], optional)
— configuration
###### Returns
Nothing (undefined).
$3
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 usinguseShortestReferences
> .
###### Fields
* useNamedReferences (boolean, default: false)&
— prefer named character references () where possibleomitOptionalSemicolons
* (boolean, default: false)useShortestReferences
— whether to omit semicolons when possible
* (boolean, default: false)
— prefer the shortest possible reference, if that results in less bytes
$3
Configuration (TypeScript type).
> ⚠️ Danger: only set allowDangerousCharacters and allowDangerousHtml if
> you completely trust the content.
> 👉 Note: allowParseErrors, bogusComments, tightAttributes, andtightDoctype
>
> 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)allowDangerousHtml
— do not encode some characters which cause XSS vulnerabilities in older
browsers
* (boolean, default: false)Raw
— allow [][raw] nodes and insert them as raw HTML; when false, Raw
nodes are encoded
* (boolean, default: false)bogusComments
— do not encode characters which cause parse errors (even though they
work), to save bytes; not used in the SVG space.
* (boolean, default: false)
— use “bogus comments” instead of comments to save byes:
instead of
* ([CharacterReferences][api-character-references],closeEmptyElements
optional)
— configure how to serialize character references
* (boolean, default: false)/
— close SVG elements without any content with slash () on the opening
tag instead of an end tag: instead of ;tightSelfClosing
see to control whether a space is used before the slash;closeSelfClosing
not used in the HTML space
* (boolean, default: false)/
— close self-closing nodes with an extra slash (): instead of
; see tightSelfClosing to control whether a space is used beforecollapseEmptyAttributes
the slash; not used in the SVG space.
* (boolean, default: false)class
— collapse empty attributes: get instead of class=""; not used inhidden
the SVG space; boolean attributes (such as ) are always collapsedomitOptionalTags
* (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