rehype-stringify

rehype plugin to serialize HTML

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
rehype-stringify
9.0.3a year ago7 years agoMinified + gzip package size for rehype-stringify in KB

Popular Searches

Readme

rehype-stringify
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
rehype plugin to add support for serializing HTML.

Contents

*   [`unified().use(rehypeStringify[, options])`](#unifieduserehypestringify-options)

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 readmerehype for info on what the rehype ecosystem is.

When should I use this?

This plugin adds support to unified for serializing HTML. You can alternatively use rehyperehype-core instead, which combines unified, rehype-parserehype-parse, and this plugin.
When you’re in a browser, trust your content, don’t need formatting options, and value a smaller bundle size, you can use rehype-dom-stringifyrehype-dom-stringify instead.
This plugin is built on hast-util-to-htmlhast-util-to-html, which turns hast syntax trees into a string. rehype focusses on making it easier to transform content by abstracting such internals away.

Install

This package is ESM onlyesm. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:
npm install rehype-stringify

In Deno with Skypack:
import rehypeStringify from 'https://cdn.skypack.dev/rehype-stringify@9?dts'

In browsers with Skypack:
<script type="module">
  import rehypeStringify from 'https://cdn.skypack.dev/rehype-stringify@9?min'
</script>

Use

Say we have the following module example.js:
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkGfm from 'remark-gfm'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'

main()

async function main() {
  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])

Add support for serializing HTML. Options are passed to hast-util-to-htmlhast-util-to-html.
options
Configuration (optional).
options.entities
Define how to create character references (Object, default: {}). Configuration is passed to stringify-entitiesstringify-entities. You can use the fields useNamedReferences, useShortestReferences, and omitOptionalSemicolons. You cannot use the fields escapeOnly, attribute, or subset).
options.upperDoctype
Use a <!DOCTYPE… instead of <!doctype…. Useless except for XHTML (boolean, default: false).
options.quote
Preferred quote to use ('"' or '\'', default: '"').
options.quoteSmart
Use the other quote if that results in less bytes (boolean, default: false).
options.preferUnquoted
Leave attributes unquoted if that results in less bytes (boolean, default: false).
Not used in the SVG space.
options.omitOptionalTags
Omit optional opening and closing tags (boolean, default: false). For example, in <ol><li>one</li><li>two</li></ol>, both </li> 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.
options.collapseEmptyAttributes
Collapse empty attributes: get class instead of class="" (boolean, default: false).
Not used in the SVG space.
👉 Note: boolean attributes (such as hidden) are always collapsed.
options.closeSelfClosing
Close self-closing nodes with an extra slash (/): <img /> instead of <img> (boolean, default: false). See tightSelfClosing to control whether a space is used before the slash.
Not used in the SVG space.
options.closeEmptyElements
Close SVG elements without any content with slash (/) on the opening tag instead of an end tag: <circle /> instead of <circle></circle> (boolean, default: false). See tightSelfClosing to control whether a space is used before the slash.
Not used in the HTML space.
options.tightSelfClosing
Do not use an extra space when closing self-closing elements: <img/> instead of <img /> (boolean, default: false).
👉 Note: only used if closeSelfClosing: true or closeEmptyElements: true.
options.tightCommaSeparatedLists
Join known comma-separated attribute values with just a comma (,), instead of padding them on the right as well (,␠, where ␠ represents a space) (boolean, default: false).
options.tightAttributes
Join attributes together, without whitespace, if possible: get class="a b"title="c d" instead of class="a b" title="c d" to save bytes (boolean, default: false).
Not used in the SVG space.
👉 Note: intentionally creates parse errors in markup (how parse errors are handled is well defined, so this works but isn’t pretty).
options.tightDoctype
Drop unneeded spaces in doctypes: <!doctypehtml> instead of <!doctype html> to save bytes (boolean, default: false).
👉 Note: intentionally creates parse errors in markup (how parse errors are handled is well defined, so this works but isn’t pretty).
options.bogusComments
Use “bogus comments” instead of comments to save byes: <?charlie> instead of <!--charlie--> (boolean, default: false).
👉 Note: intentionally creates parse errors in markup (how parse errors are handled is well defined, so this works but isn’t pretty).
options.allowParseErrors
Do not encode characters which cause parse errors (even though they work), to save bytes (boolean, default: false).
Not used in the SVG space.
👉 Note: intentionally creates parse errors in markup (how parse errors are handled is well defined, so this works but isn’t pretty).
options.allowDangerousCharacters
Do not encode some characters which cause XSS vulnerabilities in older browsers (boolean, default: false).
⚠️ Danger: only set this if you completely trust the content.
options.allowDangerousHtml
Allow raw nodes and insert them as raw HTML. When falsey, encodes raw nodes (boolean, default: false).
⚠️ Danger: only set this if you completely trust the content.
options.space
Which space the document is in ('svg' or 'html', default: 'html').
When an <svg> element is found in the HTML space, rehype-stringify already automatically switches to and from the SVG space when entering and exiting it.
👉 Note: rehype is not an XML parser. It supports SVG as embedded in HTML. It does not support the features available in XML. Passing SVG files might break but fragments of modern SVG should be fine.
options.voids
Tag names of elements to serialize without closing tag (Array<string>, default: html-void-elementshtml-void-elements).
Not used in the SVG space.
👉 Note: It’s highly unlikely that you want to pass this. It’s only really applicable to the hast-util-to-html utility.

Syntax

HTML is parsed according to WHATWG HTML (the living standard), which is also followed by browsers such as Chrome and Firefox.

Syntax tree

The syntax tree format used in rehype is hast.

Types

This package is fully typed with TypeScript. The extra types Options are exported.

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

Security

As rehype works on HTML, and improper use of HTML can open you up to a cross-site scripting (XSS)xss attack, use of rehype can also be unsafe. Use rehype-sanitizerehype-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 policysecurity.

Contribute

See contributing.mdcontributing in rehypejs/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.

Sponsor

Support this effort and give back by sponsoring on OpenCollectivecollective!

Vercel

 Motif

 HashiCorp

 GitBook

 Gatsby
Netlify

 Coinbase

 ThemeIsle

 Expo

 Boost Note

 Holloway

You?

License

MITlicense © Titus Wormerauthor