Registry / serialization / hast-util-excerpt

hast-util-excerpt

library2.0.0jsnpmunverified

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.

serialization

npm install hast-util-excerpt

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-EXCERPT

hast-util-excerpt

serializationjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

excerpt

✓ import { excerpt } from 'hast-util-excerpt';

✗ const excerpt = require('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.

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', ''), h('p', 'More detailed content.') ]); const customExcerptResult = excerpt(customCommentTree, { comment: '' }); console.log('\nExcerpt with custom comment:\n', JSON.stringify(customExcerptResult, null, 2));

Debug

Known issues

breakingVersion 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.

affects: >=2.0.0

breakingVersion 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`.

affects: >=2.0.0

breakingThe 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.

affects: >=2.0.0

gotchaThe `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 })`.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

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

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

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.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/hast-util-excerpt ↗

packagehttps://www.npmjs.com/package/hast-util-excerpt ↗