hast-util-truncate
hast utility to truncate the tree to a certain number of characters.
Contents
What is this?
This package is a utility that takes a hast (HTML) syntax tree and truncates it to a certain number of characters, while otherwise preserving the tree structure.
When should I use this?
This is a small utility useful when you need to create a shorter version of a potentially long document.
This utility is similar to hast-util-excerpt, which truncates a tree to a certain comment.
The rehype plugin rehype-infer-description-meta wraps both this utility and hast-util-excerpt to figure out a description of a document, for use with rehype-meta.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install hast-util-truncate
In Deno with esm.sh:
import {truncate} from 'https://esm.sh/hast-util-truncate@2'
In browsers with esm.sh:
<script type="module">
import {truncate} from 'https://esm.sh/hast-util-truncate@2?bundle'
</script>
Use
Say our module example.js looks as follows:
import {h} from 'hastscript'
import {truncate} from 'hast-util-truncate'
const tree = h('p', [
'Lorem ipsum dolor sit amet, ',
h('em', 'consectetur'),
'adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud'
])
console.log(truncate(tree, {ellipsis: '…'}));
…now running node example.js yields:
{
type: 'element',
tagName: 'p',
properties: {},
children: [
{type: 'text', value: 'Lorem ipsum dolor sit amet, '},
{
type: 'element',
tagName: 'em',
properties: {},
children: [{type: 'text', value: 'consectetur'}]
},
{
type: 'text',
value: 'adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim…'
}
]
}
API
This package exports the identifier truncate. There is no default export.
truncate(tree[, options])
Truncate the tree to a certain number of characters.
Parameters
tree (Node) — tree to truncateoptions (Options, optional) — configuration
Returns
Truncated copy of tree (Node).
Options
Configuration (TypeScript type).
Fields
options.size
Number of characters to truncate to (number, default: 140).
options.ellipsis
Value to use at truncation point (string, optional).
options.maxCharacterStrip
How far to walk back (number, default: 30). The algorithm attempts to break right after a word rather than the exact size. Take for example the |, which is the actual break defined by size, and the … is the location where the ellipsis is placed: This… an|d that. Breaking at | would at best look bad but could likely result in things such as ass… for assignment, which is not ideal. maxCharacterStrip defines how far back the algorithm will walk to find a pretty word break. This prevents a potential slow operation on larger sizes without any whitespace. If maxCharacterStrip characters are walked back and no nice break point is found, the bad break point is used. Set maxCharacterStrip: 0 to not find a nice break.
options.ignore
Nodes to exclude from the resulting tree (Array<Node>). These are not counted towards size.
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, hast-util-truncate@^2, compatible with Node.js 16.
Security
Use of hast-util-truncate should be safe if the tree is already safe and you’re not using user content in options. When in doubt, use hast-util-sanitize.
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