Registry / serialization / mdast-util-heading-range

mdast-util-heading-range

library4.0.0jsnpmunverified

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.

serialization

npm install mdast-util-heading-range

github ↗package ↗

INSTALL

IMPORT

SIG · MDAST-UTIL-HEADING

mdast-util-heading-range

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

headingRange

✓ import { headingRange } from 'mdast-util-heading-range'

✗ const headingRange = require('mdast-util-heading-range')

This package is ESM-only since v3.0.0. CommonJS `require()` is not supported.

Info

✓ import type { Info } from 'mdast-util-heading-range'

Import `Info` as a type for the fourth argument of the handler function. In v4, the `ZoneInfo` type was renamed to `Info`.

Handler

✓ import type { Handler } from 'mdast-util-heading-range'

Import `Handler` as a type for defining the callback function signature when using TypeScript.

Demonstrates finding the 'Foo' heading section and replacing its content with new nodes using the `headingRange` utility.

import {read} from 'to-vfile'; import {remark} from 'remark'; import {headingRange} from 'mdast-util-heading-range'; const markdownContent = `# Foo\n\nBar.\n\n# Baz\n\nOther content.\n\n## Sub Heading\n\nSub content.`; async function processMarkdown() { const file = await remark() .use(myPluginThatReplacesFoo) .process(String(markdownContent)); console.log(String(file)); } /** @type {import('unified').Plugin<[], import('mdast').Root>} */ function myPluginThatReplacesFoo() { return function (tree) { headingRange(tree, 'Foo', function (start, nodes, end) { // This handler receives the 'Foo' heading (start), // nodes between 'Foo' and 'Baz' (nodes), and the 'Baz' heading (end). // It replaces the content of the 'Foo' section. return [ start, {type: 'paragraph', children: [{type: 'text', value: 'Content updated by mdast-util-heading-range.'}]}, {type: 'list', children: [{type: 'listItem', children: [{type: 'paragraph', children: [{type: 'text', value: 'New list item.'}]}]}]}, end ] }) } } processMarkdown();

Debug

Known issues

breakingVersion 4.0.0 requires Node.js 16 or higher. Older Node.js versions are no longer supported.

fix

Upgrade your Node.js environment to version 16 or newer. Use `nvm install 16` or similar.

affects: >=4.0.0

breakingThe package now uses `export` maps, which affects how it's imported in some environments, particularly those relying on internal or non-standard paths.

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.

affects: >=4.0.0

breakingThe `ZoneInfo` TypeScript type was removed and renamed to `Info` in version 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 '...'`.

affects: >=4.0.0

breakingVersion 3.0.0 transitioned to an ESM-only package. CommonJS `require()` is no longer supported.

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.

affects: >=3.0.0

gotchaWhen `ignoreFinalDefinitions: true` is used, the handler will exclude final definition nodes found within a section.

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.

affects: >=2.1.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to `require()` an ESM-only package.

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

TypeError: Cannot read properties of undefined (reading 'type')

Passing an improperly typed MDAST tree or `Node` to `headingRange` or its handler, especially after recent type updates.

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.

Error: `test` must be a string, array of strings, regular expression, function, or `options` object.

The `test` argument for `headingRange` is not in a valid format.

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

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/mdast-util-heading-range ↗

packagehttps://www.npmjs.com/package/mdast-util-heading-range ↗