Hast-util-format NPM

hast-util-format

hast utility to format whitespace in HTML.

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