hast-util-format
v1.1.0
Published
Format whitespace in HTML
Downloads
201,525
Readme
hast-util-format
hast utility to format whitespace in HTML.
Contents
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-formatIn Deno with esm.sh:
import {format} from 'https://esm.sh/hast-util-format@1'In browsers with esm.sh:
<script type="module">
import {format} from 'https://esm.sh/hast-util-format@1?bundle'
</script>Use
Say we have the following example.html:
<!doCTYPE HTML><html>
<head>
<title>Hello!</title>
<meta charset=utf8>
</head>
<body><section> <p>hi there</p>
</section>
</body>
</html>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:
<!doctype html>
<html>
<head>
<title>Hello!</title>
<meta charset="utf8">
</head>
<body>
<section>
<p>hi there</p>
</section>
</body>
</html>👉 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 twoindent?(string | number | null | undefined) — indentation per level (default:2); whennumber, uses that amount of spaces; whenstring, uses that per indentation levelindentInitial?(boolean | null | undefined) — whether to indent the first level (default:true); this is usually the<html>, thus not indentingheadandbody
format(tree, options)
Format whitespace in HTML.
Parameters
tree(Root) — treeoptions?(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.
Related
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.