rehype-format
Advanced tools
rehype-format - npm Package Compare versions
Comparing version 4.0.0 to 4.0.1
| /** | ||
| * @type {import('unified').Plugin<[Options?] | void[], Root>} | ||
| * Format whitespace in HTML. | ||
| * | ||
| * @type {import('unified').Plugin<[Options?] | Array<void>, Root>} | ||
| */ | ||
@@ -29,3 +31,3 @@ export default function rehypeFormat( | ||
| /** | ||
| * List of tag names to join with a blank line (`Array.<string>`, default: | ||
| * List of tag names to join with a blank line (`Array<string>`, default: | ||
| * `[]`). | ||
@@ -32,0 +34,0 @@ * These tags, when next to each other, are joined by a blank line (`\n\n`). |
12
index.js
@@ -16,4 +16,4 @@ /** | ||
| * This is usually the `<html>`, thus not indenting `head` and `body`. | ||
| * @property {string[]} [blanks=[]] | ||
| * List of tag names to join with a blank line (`Array.<string>`, default: | ||
| * @property {Array<string>} [blanks=[]] | ||
| * List of tag names to join with a blank line (`Array<string>`, default: | ||
| * `[]`). | ||
@@ -36,3 +36,5 @@ * These tags, when next to each other, are joined by a blank line (`\n\n`). | ||
| /** | ||
| * @type {import('unified').Plugin<[Options?] | void[], Root>} | ||
| * Format whitespace in HTML. | ||
| * | ||
| * @type {import('unified').Plugin<[Options?] | Array<void>, Root>} | ||
| */ | ||
@@ -110,3 +112,3 @@ export default function rehypeFormat(options = {}) { | ||
| /** @type {Child[]} */ | ||
| /** @type {Array<Child>} */ | ||
| const result = [] | ||
@@ -146,3 +148,3 @@ /** @type {Child|undefined} */ | ||
| /** | ||
| * @param {Child[]} list | ||
| * @param {Array<Child>} list | ||
| * @param {number} level | ||
@@ -149,0 +151,0 @@ * @param {Child} [next] |
| { | ||
| "name": "rehype-format", | ||
| "version": "4.0.0", | ||
| "version": "4.0.1", | ||
| "description": "rehype plugin to format HTML", | ||
@@ -36,3 +36,3 @@ "license": "MIT", | ||
| "dependencies": { | ||
| "@types/hast": "^2.3.2", | ||
| "@types/hast": "^2.0.0", | ||
| "hast-util-embedded": "^2.0.0", | ||
@@ -53,4 +53,4 @@ "hast-util-is-element": "^2.0.0", | ||
| "rehype": "^12.0.0", | ||
| "remark-cli": "^9.0.0", | ||
| "remark-preset-wooorm": "^8.0.0", | ||
| "remark-cli": "^10.0.0", | ||
| "remark-preset-wooorm": "^9.0.0", | ||
| "rimraf": "^3.0.0", | ||
@@ -61,3 +61,3 @@ "tape": "^5.0.0", | ||
| "typescript": "^4.0.0", | ||
| "xo": "^0.42.0" | ||
| "xo": "^0.47.0" | ||
| }, | ||
@@ -64,0 +64,0 @@ "scripts": { |
257
readme.md
@@ -11,11 +11,54 @@ # rehype-format | ||
| [**rehype**][rehype] plugin to format HTML. | ||
| **[rehype][]** plugin to format HTML. | ||
| ## Contents | ||
| * [What is this?](#what-is-this) | ||
| * [When should I use this?](#when-should-i-use-this) | ||
| * [Install](#install) | ||
| * [Use](#use) | ||
| * [API](#api) | ||
| * [`unified().use(rehypeFormat[, options])`](#unifieduserehypeformat-options) | ||
| * [Examples](#examples) | ||
| * [Example: markdown input (remark)](#example-markdown-input-remark) | ||
| * [Example: tabs and blank lines (`indent`, `blanks`)](#example-tabs-and-blank-lines-indent-blanks) | ||
| * [Types](#types) | ||
| * [Compatibility](#compatibility) | ||
| * [Security](#security) | ||
| * [Related](#related) | ||
| * [Contribute](#contribute) | ||
| * [License](#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 white space 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. | ||
| A different package, [`rehype-stringify`][rehype-stringify], controls how HTML | ||
| is actually printed: which quotes to use, whether to put a `/` on `<img />`, | ||
| etc. | ||
| Yet another project, [`rehype-minify`][rehype-minify], does the inverse: improve | ||
| the size of HTML source code by making it hard to read. | ||
| ## Install | ||
| This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): | ||
| Node 12+ is needed to use it and it must be `import`ed instead of `require`d. | ||
| This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). | ||
| In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: | ||
| [npm][]: | ||
| ```sh | ||
@@ -25,5 +68,19 @@ npm install rehype-format | ||
| In Deno with [Skypack][]: | ||
| ```js | ||
| import rehypeFormat from 'https://cdn.skypack.dev/rehype-format@4?dts' | ||
| ``` | ||
| In browsers with [Skypack][]: | ||
| ```html | ||
| <script type="module"> | ||
| import rehypeFormat from 'https://cdn.skypack.dev/rehype-format@4?min' | ||
| </script> | ||
| ``` | ||
| ## Use | ||
| Say we have the following file, `index.html`: | ||
| Say we have the following file `index.html`: | ||
@@ -42,27 +99,26 @@ ```html | ||
| And our module, `example.js`, looks as follows: | ||
| And our module `example.js` looks as follows: | ||
| ```js | ||
| import {readSync} from 'to-vfile' | ||
| import {reporter} from 'vfile-reporter' | ||
| import {rehype} from 'rehype' | ||
| import {read} from 'to-vfile' | ||
| import {unified} from 'unified' | ||
| import rehypeParse from 'rehype-parse' | ||
| import rehypeFormat from 'rehype-format' | ||
| import rehypeStringify from 'rehype-stringify' | ||
| const file = readSync('index.html') | ||
| main() | ||
| rehype() | ||
| .use(rehypeFormat) | ||
| .process(file) | ||
| .then((file) => { | ||
| console.error(reporter(file)) | ||
| console.log(String(file)) | ||
| }) | ||
| async function main() { | ||
| const file = await unified() | ||
| .use(rehypeParse) | ||
| .use(rehypeFormat) | ||
| .use(rehypeStringify) | ||
| .process(await read('index.html')) | ||
| console.log(String(file)) | ||
| } | ||
| ``` | ||
| Now, running `node example` yields: | ||
| Now running `node example.js` yields: | ||
| ```txt | ||
| index.html: no issues found | ||
| ``` | ||
| ```html | ||
@@ -90,19 +146,12 @@ <!doctype html> | ||
| Format whitespace in the processed tree. | ||
| Format whitespace in HTML. | ||
| * Collapse all white space (to a single space or newline) | ||
| * Remove unneeded white space | ||
| * Inject needed newlines and indentation | ||
| * Indent previously collapsed newlines properly | ||
| ##### `options` | ||
| All superfluous white space is removed. | ||
| However, as newlines are kept (and later properly indented), your code will | ||
| still line-wrap as expected. | ||
| Configuration (optional). | ||
| ##### `options` | ||
| ###### `options.indent` | ||
| Indentation per level (`number`, `string`, default: `2`). | ||
| When number, uses that amount of spaces. | ||
| When `number`, uses that amount of spaces. | ||
| When `string`, uses that per indentation level. | ||
@@ -113,7 +162,8 @@ | ||
| Whether to indent the first level (`boolean`, default: `true`). | ||
| This is usually the `<html>`, thus not indenting `head` and `body`. | ||
| The initial element is usually the `<html>` element, so when this is set to | ||
| `false`, its children `<head>` and `<body>` would not be indented. | ||
| ###### `options.blanks` | ||
| List of tag names to join with a blank line (`Array.<string>`, default: `[]`). | ||
| List of tag names to join with a blank line (`Array<string>`, default: `[]`). | ||
| These tags, when next to each other, are joined by a blank line (`\n\n`). | ||
@@ -123,9 +173,116 @@ For example, when `['head', 'body']` is given, a blank line is added between | ||
| ## 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: | ||
| ```js | ||
| import {unified} from 'unified' | ||
| import remarkParse from 'remark-parse' | ||
| import remarkRehype from 'remark-rehype' | ||
| import rehypeDocument from 'rehype-document' | ||
| import rehypeFormat from 'rehype-format' | ||
| import rehypeStringify from 'rehype-stringify' | ||
| main() | ||
| async function main() { | ||
| const file = await unified() | ||
| .use(remarkParse) | ||
| .use(remarkRehype) | ||
| .use(rehypeDocument, {title: 'Neptune'}) | ||
| .use(rehypeFormat) | ||
| .use(rehypeStringify) | ||
| .process('# Hello, Neptune!') | ||
| console.log(String(file)) | ||
| } | ||
| ``` | ||
| Yields: | ||
| ```html | ||
| <!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: | ||
| ```js | ||
| import {unified} from 'unified' | ||
| import rehypeParse from 'rehype-parse' | ||
| import rehypeFormat from 'rehype-format' | ||
| import rehypeStringify from 'rehype-stringify' | ||
| main() | ||
| async function main() { | ||
| const file = await unified() | ||
| .use(rehypeParse) | ||
| .use(rehypeFormat, {indent: '\t', blanks: ['head', 'body']}) | ||
| .use(rehypeStringify) | ||
| .process('<h1>Hi!</h1><p>Hello, Venus!</p>') | ||
| console.log(String(file)) | ||
| } | ||
| ``` | ||
| Yields: | ||
| <!--lint ignore no-tabs--> | ||
| ```html | ||
| <html> | ||
| <head></head> | ||
| <body> | ||
| <h1>Hi!</h1> | ||
| <p>Hello, Venus!</p> | ||
| </body> | ||
| </html> | ||
| ``` | ||
| > 👉 **Note**: the added tags (`html`, `head`, and `body`) do not come from this | ||
| > plugin. | ||
| > They’re instead added by `rehype-parse`, which in document mode (default), | ||
| > adds them according to the HTML spec. | ||
| ## Types | ||
| This package is fully typed with [TypeScript][]. | ||
| It exports an `Options` type, which specifies the interface of the accepted | ||
| options. | ||
| ## Compatibility | ||
| Projects maintained by the unified collective are compatible with all maintained | ||
| versions of Node.js. | ||
| As of now, that is Node.js 12.20+, 14.14+, and 16.0+. | ||
| Our projects sometimes work with older versions, but this is not guaranteed. | ||
| 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 white space in the syntax tree. | ||
| Use of `rehype-format` changes white space in the tree. | ||
| White space 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)][xss] attack. | ||
| When in doubt, use [`rehype-sanitize`][sanitize]. | ||
| When in doubt, use [`rehype-sanitize`][rehype-sanitize]. | ||
@@ -135,11 +292,11 @@ ## Related | ||
| * [`rehype-minify`](https://github.com/rehypejs/rehype-minify) | ||
| — Minify HTML | ||
| — minify HTML | ||
| * [`rehype-document`](https://github.com/rehypejs/rehype-document) | ||
| — Wrap a document around a fragment | ||
| — wrap a fragment in a document | ||
| * [`rehype-sanitize`](https://github.com/rehypejs/rehype-sanitize) | ||
| — Sanitize HTML | ||
| — sanitize HTML | ||
| * [`rehype-toc`](https://github.com/JS-DevTools/rehype-toc) | ||
| — Add a table of contents (TOC) | ||
| — add a table of contents (TOC) | ||
| * [`rehype-section`](https://github.com/agentofuser/rehype-section) | ||
| — Wrap headings and their contents in sections | ||
| — wrap headings and their contents in sections | ||
@@ -188,2 +345,4 @@ ## Contribute | ||
| [skypack]: https://www.skypack.dev | ||
| [npm]: https://docs.npmjs.com/cli/install | ||
@@ -203,6 +362,14 @@ | ||
| [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting | ||
| [typescript]: https://www.typescriptlang.org | ||
| [unified]: https://github.com/unifiedjs/unified | ||
| [rehype]: https://github.com/rehypejs/rehype | ||
| [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting | ||
| [rehype-stringify]: https://github.com/rehypejs/rehype/tree/main/packages/rehype-stringify | ||
| [sanitize]: https://github.com/rehypejs/rehype-sanitize | ||
| [rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize | ||
| [rehype-minify]: https://github.com/rehypejs/rehype-minify |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by31.18%
19369
- Lines of code
- increased by2.06%
198
- Number of lines in readme file
- increased by83.5%
367
- Number of medium supply chain risk alerts
- decreased by-100%
0
Dependency changes
Updated@types/hast@^2.0.0