unified

Project: syntax-tree/hast-util-truncate

Package: hast-util-truncate@1.0.1

  1. Dependents: 1
  2. hast utility to truncate the tree to a certain number of characters
  1. util 143
  2. utility 139
  3. unist 127
  4. html 121
  5. hast 72
  6. hast-util 46
  7. excerpt 4
  8. summary 4
  9. truncate 2

hast-util-truncate

Build Coverage Downloads Size Sponsors Backers Chat

hast utility to truncate the tree to a certain number of characters.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install hast-util-truncate

Use

Say we have the following module, example.js:

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 following identifiers: truncate. There is no default export.

truncate(tree, options?)

Truncate the tree to a certain number of characters.

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.

Returns

Node — Truncated copy of tree

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