{"id":10993,"library":"hast-util-excerpt","title":"hast-util-excerpt: HTML Tree Excerpt Utility","description":"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 `<!--more-->`. 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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-excerpt","tags":["javascript","unist","hast","hast-util","util","utility","html","excerpt","typescript"],"install":[{"cmd":"npm install hast-util-excerpt","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-excerpt","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-excerpt","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only since v2; CommonJS `require` is not supported. Node.js 16+ is required.","wrong":"const excerpt = require('hast-util-excerpt');","symbol":"excerpt","correct":"import { excerpt } from 'hast-util-excerpt';"},{"note":"For Deno or browser environments, use esm.sh directly. For browsers, append `?bundle` for self-contained usage.","symbol":"excerpt (Deno/Browser)","correct":"import {excerpt} from 'https://esm.sh/hast-util-excerpt@2'"}],"quickstart":{"code":"import { u } from 'unist-builder';\nimport { h } from 'hastscript';\nimport { excerpt } from 'hast-util-excerpt';\n\nconst tree = h('p', [\n  'Lorem ipsum dolor sit amet, ',\n  h('em', 'consectetur'),\n  'adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',\n  u('comment', 'more'),\n  'Ut enim ad minim veniam, quis nostrud'\n]);\n\nconst result = excerpt(tree);\nconsole.log(JSON.stringify(result, null, 2));\n\nconst customCommentTree = h('div', [\n  h('h1', 'My Article'),\n  h('p', 'Introduction to the topic.'),\n  u('comment', '<!-- break -->'),\n  h('p', 'More detailed content.')\n]);\n\nconst customExcerptResult = excerpt(customCommentTree, { comment: '<!-- break -->' });\nconsole.log('\\nExcerpt with custom comment:\\n', JSON.stringify(customExcerptResult, null, 2));","lang":"typescript","description":"Demonstrates truncating a hast (HTML) tree at a `<!--more-->` comment marker, including an example with a custom comment."},"warnings":[{"fix":"Migrate your project to use ES modules (`import`/`export`) or stick to `hast-util-excerpt@1` if CommonJS is strictly necessary.","message":"Version 2.0.0 and above are ESM-only. CommonJS `require()` is no longer supported.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"Version 2.0.0 and above require Node.js 16 or newer.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure you only import and use the officially exported `excerpt` function. Avoid deep imports or relying on internal module structures.","message":"The package now uses the `exports` field in `package.json`, which means accessing private, non-exported APIs directly is no longer possible.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If your excerpt comment is expected to be deep within a very large document, increase `maxSearchSize` in the options: `excerpt(tree, { maxSearchSize: 5000 })`.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` to import `hast-util-excerpt` in a project configured for ES Modules, or after updating to v2+.","error":"ReferenceError: require is not defined"},{"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.","cause":"Using an outdated Node.js version (older than 16) with `hast-util-excerpt@2+`, or incorrect module resolution for an ESM-only package.","error":"ERR_MODULE_NOT_FOUND: Cannot find module 'hast-util-excerpt' imported from ..."},{"fix":"Ensure you are using named import: `import { excerpt } from 'hast-util-excerpt';`. The `excerpt` function is not a default export.","cause":"Incorrect import statement (e.g., default import) when the package provides only named exports, or attempting to destructure `require()` in an incompatible setup.","error":"TypeError: (0, _hast_util_excerpt.excerpt) is not a function"}],"ecosystem":"npm"}