{"id":11288,"library":"mdast-util-heading-range","title":"MDAST Heading Range Utility","description":"mdast-util-heading-range is a utility for working with Markdown Abstract Syntax Trees (MDAST) to identify and manipulate content sections defined by headings. It allows developers to find a specific heading, capture all content nodes within its section (up to the next heading of the same or lower depth, or the end of the document), and then apply a handler function to modify or replace that content. The current stable version is 4.0.0, released in a mostly ad-hoc fashion following the syntax-tree ecosystem's release schedule, typically with minor versions for features and patch versions for fixes. Key differentiators include its focus on heading-based content segmentation, offering a programmatic way to update generated sections (like a Table of Contents), and its integration within the broader `unified` and `remark` ecosystem. It is an ESM-only package since version 3.0.0 and requires Node.js 16 or higher as of version 4.0.0.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-util-heading-range","tags":["javascript","unist","mdast","mdast-util","util","utility","markdown","heading","range","typescript"],"install":[{"cmd":"npm install mdast-util-heading-range","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-util-heading-range","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-util-heading-range","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only since v3.0.0. CommonJS `require()` is not supported.","wrong":"const headingRange = require('mdast-util-heading-range')","symbol":"headingRange","correct":"import { headingRange } from 'mdast-util-heading-range'"},{"note":"Import `Info` as a type for the fourth argument of the handler function. In v4, the `ZoneInfo` type was renamed to `Info`.","symbol":"Info","correct":"import type { Info } from 'mdast-util-heading-range'"},{"note":"Import `Handler` as a type for defining the callback function signature when using TypeScript.","symbol":"Handler","correct":"import type { Handler } from 'mdast-util-heading-range'"}],"quickstart":{"code":"import {read} from 'to-vfile';\nimport {remark} from 'remark';\nimport {headingRange} from 'mdast-util-heading-range';\n\nconst markdownContent = `# Foo\\n\\nBar.\\n\\n# Baz\\n\\nOther content.\\n\\n## Sub Heading\\n\\nSub content.`;\n\nasync function processMarkdown() {\n  const file = await remark()\n    .use(myPluginThatReplacesFoo)\n    .process(String(markdownContent));\n\n  console.log(String(file));\n}\n\n/** @type {import('unified').Plugin<[], import('mdast').Root>} */\nfunction myPluginThatReplacesFoo() {\n  return function (tree) {\n    headingRange(tree, 'Foo', function (start, nodes, end) {\n      // This handler receives the 'Foo' heading (start), \n      // nodes between 'Foo' and 'Baz' (nodes), and the 'Baz' heading (end).\n      // It replaces the content of the 'Foo' section.\n      return [\n        start,\n        {type: 'paragraph', children: [{type: 'text', value: 'Content updated by mdast-util-heading-range.'}]},\n        {type: 'list', children: [{type: 'listItem', children: [{type: 'paragraph', children: [{type: 'text', value: 'New list item.'}]}]}]},\n        end\n      ]\n    })\n  }\n}\n\nprocessMarkdown();","lang":"typescript","description":"Demonstrates finding the 'Foo' heading section and replacing its content with new nodes using the `headingRange` utility."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer. Use `nvm install 16` or similar.","message":"Version 4.0.0 requires Node.js 16 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure you are using the public API entry points. Avoid using private or undocumented internal paths. Modern bundlers and Node.js generally handle `export` maps correctly with standard imports.","message":"The package now uses `export` maps, which affects how it's imported in some environments, particularly those relying on internal or non-standard paths.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update all type imports and references from `ZoneInfo` to `Info`. For example, `import type { ZoneInfo } from '...'` becomes `import type { Info } from '...'`.","message":"The `ZoneInfo` TypeScript type was removed and renamed to `Info` in version 4.0.0.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Migrate your project to use ES modules (`import`/`export`) or use dynamic `import()` for loading the package. Ensure your `package.json` includes `\"type\": \"module\"` or uses `.mjs` file extensions.","message":"Version 3.0.0 transitioned to an ESM-only package. CommonJS `require()` is no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Be aware of this option's effect if your sections might contain definitions. If you need to process or retain final definitions within a section, ensure `ignoreFinalDefinitions` is not set to `true` or handle them explicitly outside the `headingRange` call.","message":"When `ignoreFinalDefinitions: true` is used, the handler will exclude final definition nodes found within a section.","severity":"gotcha","affected_versions":">=2.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { headingRange } = require('mdast-util-heading-range')` to `import { headingRange } from 'mdast-util-heading-range'` and ensure your project is configured for ES modules (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to `require()` an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure the `tree` argument is a valid `mdast.Root` node and that any nodes returned by the handler conform to `mdast.Node` types. Review type definitions, especially after `v4.0.0`'s `@types/mdast` update.","cause":"Passing an improperly typed MDAST tree or `Node` to `headingRange` or its handler, especially after recent type updates.","error":"TypeError: Cannot read properties of undefined (reading 'type')"},{"fix":"Provide a string for the heading text, an array of strings, a regular expression, a test function, or an options object with a `test` property. Example: `headingRange(tree, 'My Heading', handler)` or `headingRange(tree, { test: 'My Heading' }, handler)`.","cause":"The `test` argument for `headingRange` is not in a valid format.","error":"Error: `test` must be a string, array of strings, regular expression, function, or `options` object."}],"ecosystem":"npm"}