GitHub - syntax-tree/hast-util-format: Format whitespace in HTML (original) (raw)

hast-util-format

hast utility to format whitespace in HTML.

What is this?
When should I use this?
Install
Use
API
- Options
- format(tree, options)
Compatibility
Related
Security
Contribute
License

What is this?

This package is a utility that formats whitespace in HTML. In short, it works as follows:

collapse all existing whitespace to either a line ending or a single space (hast-util-minify-whitespace)
remove those spaces and line endings if they do not contribute to the document
inject needed line endings
indent previously collapsed line endings properly

When should I use this?

This package is useful when you want to improve the readability of an HTML fragment as it adds insignificant but pretty whitespace between elements. The plugin rehype-format uses this package to format HTML at the plugin level. The package hast-util-minify-whitespace does the inverse.

Install

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

npm install hast-util-format

In Deno with esm.sh:

import {format} from 'https://esm.sh/hast-util-format@1'

In browsers with esm.sh:

Use

Say we have the following example.html:

Hello!

hi there

Say we have the following example.js:

import fs from 'node:fs/promises' import {format} from 'hast-util-format' import {fromHtml} from 'hast-util-from-html' import {toHtml} from 'hast-util-to-html'

const document = await fs.readFile('example.html', 'utf8')

const tree = fromHtml(document)

format(tree)

const result = toHtml(tree)

console.log(result)

…now running node example.js yields:

Hello!

hi there

👉 Note: some of the changes have been made by hast-util-to-html.

API

`Options`

Configuration.

Fields

blanks? (Array<string> | null | undefined) — list of tag names to join with a blank line (default: []); these tags, when next to each other, are joined by a blank line (\n\n); for example, when ['head', 'body'] is given, a blank line is added between these two
indent? (string | number | null | undefined) — indentation per level (default: 2); when number, uses that amount of spaces; when string, uses that per indentation level
indentInitial? (boolean | null | undefined) — whether to indent the first level (default: true); this is usually the <html>, thus not indenting head and body

`format(tree, options)`

Format whitespace in HTML.

Parameters

tree (Root) — tree
options? (Options | null | undefined) — configuration (optional)

Returns

Nothing (undefined).

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-format@1, compatible with Node.js 16.

hast-util-minify-whitespace— minify whitespace between elements

Security

This package is safe.

Contribute

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.