MDAST Heading Range Utility

Common errors

• ERR_REQUIRE_ESM

  cause 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')

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

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

Warnings

• breaking Version 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.
• breaking The 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.
• breaking The `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 '...'`.
• breaking Version 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.
• gotcha When `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.

Install

• npm install mdast-util-heading-range npm
• yarn add mdast-util-heading-range yarn
• pnpm add mdast-util-heading-range pnpm

Imports

• headingRange
  wrong:

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

  correct:

  import { headingRange } from '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.

Quickstart

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();