hast utility to serialize hast as HTML.
- What is this?
- When should I use this?
- Install
- Use
- API
- Syntax
- Types
- Compatibility
- Security
- Related
- Contribute
- License
This package is a utility that turns a hast tree into a string of HTML.
You can use this utility when you want to get the serialized HTML that is represented by the syntax tree, either because you’re done with the syntax tree, or because you’re integrating with another tool that does not support syntax trees.
This utility has many options to configure how the HTML is serialized. These options help when building tools that make output pretty (e.g., formatters) or ugly (e.g., minifiers).
The utility hast-util-from-html
does the inverse of
this utility.
It turns HTML into hast.
The rehype plugin rehype-stringify
wraps this utility to
also serialize HTML at a higher-level (easier) abstraction.
This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with npm:
npm install hast-util-to-html
In Deno with esm.sh
:
import {toHtml} from "https://esm.sh/hast-util-to-html@8"
In browsers with esm.sh
:
<script type="module">
import {toHtml} from "https://esm.sh/hast-util-to-html@8?bundle"
</script>
Show install command for this example
npm install hastscript hast-util-to-html
import {h} from 'hastscript'
import {toHtml} from 'hast-util-to-html'
var tree = h('.alpha', [
'bravo ',
h('b', 'charlie'),
' delta ',
h('a.echo', {download: true}, 'foxtrot')
])
console.log(toHtml(tree))
Yields:
<div class="alpha">bravo <b>charlie</b> delta <a class="echo" download>foxtrot</a></div>
This package exports the identifier toHtml
.
There is no default export.
Serialize hast (Node
, Array<Node>
) as HTML.
Configuration (optional).
Define how to create character references (Object
, default: {}
).
Configuration is passed to stringify-entities
.
You can use the fields useNamedReferences
, useShortestReferences
, and
omitOptionalSemicolons
.
You cannot use the fields escapeOnly
, attribute
, or subset
).
Use a <!DOCTYPE…
instead of <!doctype…
.
Useless except for XHTML (boolean
, default: false
).
Preferred quote to use ('"'
or '\''
, default: '"'
).
Use the other quote if that results in less bytes (boolean
, default: false
).
Leave attributes unquoted if that results in less bytes (boolean
, default:
false
).
Not used in the SVG space.
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.
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.
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.
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.
Do not use an extra space when closing self-closing elements: <img/>
instead
of <img />
(boolean
, default: false
).
👉 Note: only used if
closeSelfClosing: true
orcloseEmptyElements: true
.
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
).
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).
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).
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).
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).
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.
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.
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: hast is not XML. It supports SVG as embedded in HTML. It does not support the features available in XML. Passing SVG might break but fragments of modern SVG should be fine. Use
xast
if you need to support SVG as XML.
Tag names of elements to serialize without closing tag (Array<string>
,
default: html-void-elements
).
Not used in the SVG space.
👉 Note: It’s highly unlikely that you want to pass this, because hast is not for XML, and HTML will not add more void elements.
Serialized HTML (string
).
HTML is serialized according to WHATWG HTML (the living standard), which is also followed by browsers such as Chrome and Firefox.
This package is fully typed with TypeScript.
It exports the additional type Options
.
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.
Use of hast-util-to-html
can open you up to a
cross-site scripting (XSS) attack if the hast tree is unsafe.
Use hast-util-santize
to make the hast tree safe.
hast-util-sanitize
— sanitize hast
See contributing.md
in syntax-tree/.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.