hast-util-excerpt

hast utility to truncate the tree to a comment.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • excerpt(tree[, options])
  • Options
• Syntax tree
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a utility that takes a hast (HTML) syntax tree and truncates it to a comment, 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, and want authors to be able to mark where that version ends.

This utility is similar to hast-util-truncate, which truncates a tree to a certain number of characters.

The rehype plugin rehype-infer-description-meta wraps both this utility and hast-util-truncate 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-excerpt

In Deno with esm.sh:

import {excerpt} from 'https://esm.sh/hast-util-excerpt@2'

In browsers with esm.sh:

<script type="module">
  import {excerpt} from 'https://esm.sh/hast-util-excerpt@2?bundle'
</script>

Use

Say our module example.js looks as follows:

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 identifier excerpt. There is no default export.

excerpt(tree[, options])

Truncate tree to a certain comment.

Parameters

• tree (Node) — tree to truncate
• options (Options) — configuration (optional)

Returns

Truncated clone of tree (Node) when a comment is found, undefined otherwise.

Options

Configuration (TypeScript type).

Fields

comment

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

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.

ignore

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

Syntax tree

The syntax tree is hast.

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-excerpt@^2, compatible with Node.js 16.

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.

Related

• hast-util-truncate — truncate the tree to a number of characters
• rehype-infer-description-meta — infer file metadata from the contents of the document
• rehype-meta — add metadata to the head of a document

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