unified

Project: syntax-tree/hast-util-excerpt

Package: hast-util-excerpt@1.0.1

  1. Dependents: 0
  2. hast utility to excerpt the tree to a comment
  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

hast-util-excerpt

Build Coverage Downloads Size Sponsors Backers Chat

hast utility to truncate the tree to a comment.

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

Use

Say we have the following module, example.js:

import {u} from 'unist-builder'
import {h} from 'hastscript'
import {excerpt} from 'hast-util-excerpt'

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.',
  u('comment', 'more'),
  'Ut enim ad minim veniam, quis nostrud'
])

console.log(excerpt(tree));

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: [Array]
    },
    {
      type: 'text',
      value:
        'adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
    }
  ]
}

API

This package exports the following identifiers: excerpt. There is no default export.

excerpt(tree, options?)

Truncate the tree to a comment.

options.comment

Comment value to search for (string, default: 'more').

options.maxSearchSize

How far to search for the comment before bailing (number, default: 2048). The goal of this project is to find user-defined explicit excerpts, that are assumed to be somewhat reasonably placed. This option prevents searching giant documents for some comment that probably won’t be found at the end.

options.ignore

Nodes to exclude from the resulting tree (Array.<Node>). These are not counted towards size.

Returns

Node? — Truncated copy of tree if there’s a comment, undefined otherwise.

Security

Use of hast-util-excerpt 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