hast-util-to-html

			Stars	Issues	Version	Updated	Created	Size
	hast-util-to-html		78	0	9.0.1	20 days ago	8 years ago

!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
hast utility to serialize hast as HTML.

What is this?
When should I use this?
Install
Use
API

*   [`toHtml(tree[, options])`](#tohtmltree-options)
*   [`CharacterReferences`](#characterreferences)
*   [`Options`](#options)
*   [`Quote`](#quote-1)
*   [`Space`](#space-1)

Syntax
Types
Compatibility
Security
Related
Contribute
License

What is this?

This package is a utility that turns a hast tree into a string of HTML.

When should I use this?

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 (such as formatters) or ugly (such as minifiers).
The utility hast-util-from-htmlhast-util-from-html does the inverse of this utility. It turns HTML into hast.
The rehype plugin rehype-stringifyrehype-stringify wraps this utility to also serialize HTML at a higher-level (easier) abstraction.

Install

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

npm install hast-util-to-html

In Deno with esm.shesmsh:

import {toHtml} from "https://esm.sh/hast-util-to-html@9"

In browsers with esm.shesmsh:

<script type="module">
  import {toHtml} from "https://esm.sh/hast-util-to-html@9?bundle"
</script>

Use

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>

API

This package exports the identifier toHtmlapi-to-html. There is no default export.

`toHtml(tree[, options])`

Serialize hast as HTML.

Parameters

tree (Nodenode or Array<Node>)

— tree to serialize

options (Optionsapi-options, optional)

— configuration

Returns

Serialized HTML (string).

`CharacterReferences`

How to serialize character references (TypeScript type).

Fields

`useNamedReferences`

Prefer named character references (&) where possible (boolean, default: false).

`omitOptionalSemicolons`

Whether to omit semicolons when possible (boolean, default: false).

⚠️ Note: this 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.

`useShortestReferences`

Prefer the shortest possible reference, if that results in less bytes (boolean, default: false).

⚠️ Note: useNamedReferences can be omitted when using useShortestReferences.

`Options`

Configuration (TypeScript type).

Fields

`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.

`allowDangerousHtml`

Allow raw nodes and insert them as raw HTML (boolean, default: false).
When false, Raw nodes are encoded.

⚠️ Danger: only set this if you completely trust the content.

`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).

`bogusComments`

Use “bogus comments” instead of comments to save byes: <?charlie> instead of  (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).

`characterReferences`

Configure how to serialize character references (CharacterReferencesapi-character-references, optional).

`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.

`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.

`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.

`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.

`preferUnquoted`

Leave attributes unquoted if that results in less bytes (boolean, default: false).
Not used in the SVG space.

`quote`

Preferred quote to use (Quoteapi-quote, default: '"').

`quoteSmart`

Use the other quote if that results in less bytes (boolean, default: false).

`space`

Which space the document is in (Spaceapi-space, default: 'html').
When an <svg> element is found in the HTML space, this package 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 xastxast if you need to support SVG as XML.

`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).

`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).

`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).

`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.

`upperDoctype`

Use a <!DOCTYPE… instead of <!doctype… (boolean, default: false).
Useless except for XHTML.

`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, because hast is not for XML, and HTML will not add more void elements.

`Quote`

HTML quotes for attribute values (TypeScript type).

Type

type Quote = '"' | "'"

`Space`

Namespace (TypeScript type).

Type

type Space = 'html' | 'svg'

Syntax

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

Types

This package is fully typed with TypeScript . It exports the additional types CharacterReferencesapi-character-references, Optionsapi-options, Quoteapi-quote, and Spaceapi-space.

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, hast-util-to-html@^9, compatible with Node.js 16.

Security

Use of hast-util-to-html can open you up to a cross-site scripting (XSS)xss attack if the hast tree is unsafe. Use hast-util-santizehast-util-sanitize to make the hast tree safe.

hast-util-sanitize

— sanitize hast

Contribute

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

hast-util-to-html

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Readme

Contents

What is this?

When should I use this?

Install

Use

API

toHtml(tree[, options])

Parameters

Returns

CharacterReferences

Fields

useNamedReferences

omitOptionalSemicolons

useShortestReferences

Options

Fields

allowDangerousCharacters

allowDangerousHtml

allowParseErrors

bogusComments

characterReferences

closeEmptyElements

closeSelfClosing

collapseEmptyAttributes

omitOptionalTags

preferUnquoted

quote

quoteSmart

space

tightAttributes

tightCommaSeparatedLists

tightDoctype

tightSelfClosing

upperDoctype

voids

Quote

Type

Space

Type

Syntax

Types

Compatibility

Security

Related

Contribute

License

Sick of boring JavaScript newsletters?

Downloads in past

`toHtml(tree[, options])`

`CharacterReferences`

`useNamedReferences`

`omitOptionalSemicolons`

`useShortestReferences`

`Options`

`allowDangerousCharacters`

`allowDangerousHtml`

`allowParseErrors`

`bogusComments`

`characterReferences`

`closeEmptyElements`

`closeSelfClosing`

`collapseEmptyAttributes`

`omitOptionalTags`

`preferUnquoted`

`quote`

`quoteSmart`

`space`

`tightAttributes`

`tightCommaSeparatedLists`

`tightDoctype`

`tightSelfClosing`

`upperDoctype`

`voids`

`Quote`

`Space`