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-format
In 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);
when number,
uses that amount of spaces; when string,
uses that per indentation levelindentInitial? (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)
— 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
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.
License
MIT © Titus Wormer
