rehype-format
v5.0.1
Published
rehype plugin to format HTML
Downloads
499,354
Readme
rehype-format
rehype plugin to format HTML.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Examples
- Types
- Compatibility
- Security
- Related
- Contribute
- License
What is this?
This package is a unified (rehype) plugin to format whitespace in HTML. In short, it works as follows:
- collapse all existing whitespace to either a line ending or a single space
- remove those spaces and line endings if they do not contribute to the document
- inject needed line endings
- indent previously collapsed line endings properly
unified is a project that transforms content with abstract syntax trees (ASTs). rehype adds support for HTML to unified. hast is the HTML AST that rehype uses. This is a rehype plugin that changes whitespace in hast.
When should I use this?
This package is useful when you want to improve the readability of HTML source
code as it adds insignificant but pretty whitespace between elements.
The package hast-util-format
does the same as this plugin
at the utility level.
A different plugin, rehype-stringify
, controls how HTML
is actually printed: which quotes to use, whether to put a /
on <img />
,
etc.
Yet another project, rehype-minify
, does the inverse: improve
the size of HTML source code by making it hard to read.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install rehype-format
In Deno with esm.sh
:
import rehypeFormat from 'https://esm.sh/rehype-format@5'
In browsers with esm.sh
:
<script type="module">
import rehypeFormat from 'https://esm.sh/rehype-format@5?bundle'
</script>
Use
Say we have the following file index.html
:
<!doCTYPE HTML><html>
<head>
<title>Hello!</title>
<meta charset=utf8>
</head>
<body><section> <p>hi there</p>
</section>
</body>
</html>
…and our module example.js
looks as follows:
import rehypeFormat from 'rehype-format'
import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import {read} from 'to-vfile'
import {unified} from 'unified'
const file = await read('index.html')
await unified()
.use(rehypeParse)
.use(rehypeFormat)
.use(rehypeStringify)
.process(file)
console.log(String(file))
…then 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>
API
This package exports no identifiers.
The default export is rehypeFormat
.
unified().use(rehypeFormat[, options])
Format whitespace in HTML.
Parameters
options
(Options
, optional) — configuration
Returns
Transform (Transformer
).
Options
Configuration (TypeScript type).
Fields
blanks
(Array<string>
, default:[]
) — 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
(number
,string
, default:2
) — indentation per level (default:2
); when number, uses that amount of spaces; whenstring
, uses that per indentation levelindentInitial
(boolean
, default:true
) — whether to indent the first level (default:true
); this is usually the<html>
, thus not indentinghead
andbody
Examples
Example: markdown input (remark)
The following example shows how remark and rehype can be combined to turn markdown into HTML, using this plugin to pretty print the HTML:
import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'
const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeDocument, {title: 'Neptune'})
.use(rehypeFormat)
.use(rehypeStringify)
.process('# Hello, Neptune!')
console.log(String(file))
Yields:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Neptune</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<h1>Hello, Neptune!</h1>
</body>
</html>
Example: tabs and blank lines (indent
, blanks
)
The following example shows how this plugin can format with tabs instead of
spaces by passing the indent
option and how blank lines can be added between
certain elements:
import rehypeFormat from 'rehype-format'
import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'
const file = await unified()
.use(rehypeParse)
.use(rehypeFormat, {blanks: ['body', 'head'], indent: '\t'})
.use(rehypeStringify)
.process('<h1>Hi!</h1><p>Hello, Venus!</p>')
console.log(String(file))
Yields:
<html>
<head></head>
<body>
<h1>Hi!</h1>
<p>Hello, Venus!</p>
</body>
</html>
👉 Note: the added tags (
html
,head
, andbody
) do not come from this plugin. They’re instead added byrehype-parse
, which in document mode (default), adds them according to the HTML spec.
Types
This package is fully typed with TypeScript.
It exports the additional type Options
.
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, rehype-format@5
,
compatible with Node.js 16.
This plugin works with rehype-parse
version 3+, rehype-stringify
version 3+,
rehype
version 5+, and unified
version 6+.
Security
Use of rehype-format
changes whitespace in the tree.
Whitespace in <script>
, <style>
, <pre>
, or <textarea>
is not modified.
If the tree is already safe, use of this plugin does not open you up for a
cross-site scripting (XSS) attack.
When in doubt, use rehype-sanitize
.
Related
rehype-minify
— minify HTMLrehype-document
— wrap a fragment in a documentrehype-sanitize
— sanitize HTMLrehype-toc
— add a table of contents (TOC)rehype-section
— wrap headings and their contents in sections
Contribute
See contributing.md
in rehypejs/.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.