hast-util-excerpt: HTML Tree Excerpt Utility

2.0.0 · active · verified Sun Apr 19

hast-util-excerpt is a utility within the unified (specifically hast/rehype) ecosystem designed to truncate an HTML (hast) syntax tree based on an explicit comment marker, typically ``. This allows authors to precisely define where a document's 'excerpt' or 'summary' should end, offering more control than character-count-based truncation methods. The current stable version is 2.0.0, which introduced significant breaking changes by moving to ESM-only and requiring Node.js 16 or newer. Releases occur as changes accumulate, rather than on a fixed schedule. Its primary differentiator is the author-defined explicit truncation point, making it suitable for content management systems or static site generators where content creators need fine-grained control over document summaries. It works by traversing the tree and stopping at the specified comment, returning a modified clone of the original tree.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use `require()` to import `hast-util-excerpt` in a project configured for ES Modules, or after updating to v2+.

fix Change `const { excerpt } = require('hast-util-excerpt');` to `import { excerpt } from 'hast-util-excerpt';` and ensure your project is set up for ES Modules (e.g., `"type": "module"` in `package.json`).
```
ERR_MODULE_NOT_FOUND: Cannot find module 'hast-util-excerpt' imported from ...
```
cause Using an outdated Node.js version (older than 16) with `hast-util-excerpt@2+`, or incorrect module resolution for an ESM-only package.

fix Update Node.js to version 16 or higher. Also, ensure your `package.json` correctly specifies `"type": "module"` if you are using ES modules, or stick to `hast-util-excerpt@1` if using an older Node.js or strictly CommonJS.
```
TypeError: (0, _hast_util_excerpt.excerpt) is not a function
```
cause Incorrect import statement (e.g., default import) when the package provides only named exports, or attempting to destructure `require()` in an incompatible setup.

fix Ensure you are using named import: `import { excerpt } from 'hast-util-excerpt';`. The `excerpt` function is not a default export.

Warnings

breaking Version 2.0.0 and above are ESM-only. CommonJS `require()` is no longer supported.
Fix: Migrate your project to use ES modules (`import`/`export`) or stick to `hast-util-excerpt@1` if CommonJS is strictly necessary.
breaking Version 2.0.0 and above require Node.js 16 or newer.
Fix: Update your Node.js runtime to version 16 or later. If you need to support older Node.js versions, use `hast-util-excerpt@1`.
breaking The package now uses the `exports` field in `package.json`, which means accessing private, non-exported APIs directly is no longer possible.
Fix: Ensure you only import and use the officially exported `excerpt` function. Avoid deep imports or relying on internal module structures.
gotcha The `maxSearchSize` option (default: 2048) limits how far the utility searches for the comment marker. If the comment is beyond this limit, `excerpt` will return `undefined`.
Fix: If your excerpt comment is expected to be deep within a very large document, increase `maxSearchSize` in the options: `excerpt(tree, { maxSearchSize: 5000 })`.

Install

npm install hast-util-excerpt npm
yarn add hast-util-excerpt yarn
pnpm add hast-util-excerpt pnpm

Imports

excerpt
wrong:
```
const excerpt = require('hast-util-excerpt');
```
correct:
```
import { excerpt } from 'hast-util-excerpt';
```
Package is ESM-only since v2; CommonJS `require` is not supported. Node.js 16+ is required.
excerpt (Deno/Browser)
```
import {excerpt} from 'https://esm.sh/hast-util-excerpt@2'
```
For Deno or browser environments, use esm.sh directly. For browsers, append `?bundle` for self-contained usage.

Quickstart

Demonstrates truncating a hast (HTML) tree at a `` comment marker, including an example with a custom comment.

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'
]);

const result = excerpt(tree);
console.log(JSON.stringify(result, null, 2));

const customCommentTree = h('div', [
  h('h1', 'My Article'),
  h('p', 'Introduction to the topic.'),
  u('comment', '<!-- break -->'),
  h('p', 'More detailed content.')
]);

const customExcerptResult = excerpt(customCommentTree, { comment: '<!-- break -->' });
console.log('\nExcerpt with custom comment:\n', JSON.stringify(customExcerptResult, null, 2));

view raw JSON →