Registry / serialization / mdast-util-toc

mdast-util-toc

library7.1.0jsnpmunverified

mdast-util-toc is a utility within the unified (specifically mdast) ecosystem for programmatically generating a table of contents from a markdown abstract syntax tree (AST). It provides a `toc` function that processes an `mdast` tree, identifying headings and constructing a new `mdast` list node representing the table of contents. The package is currently stable at version 7.1.0, with minor and patch releases occurring periodically, and major versions introducing breaking changes like ESM-only support or Node.js version bumps. Key differentiators include its tight integration with the `mdast` AST format, allowing for flexible programmatic manipulation, and its robust options for controlling the TOC generation, such as specifying heading depth (`minDepth`, `maxDepth`), skipping specific headings, and defining parent node types. It's often used indirectly via `remark-toc` for simpler integration into `remark` pipelines, which handles the injection of the generated TOC back into the document. Its focus is purely on AST transformation, making it highly composable.

serialization

npm install mdast-util-toc

github ↗package ↗

INSTALL

IMPORT

SIG · MDAST-UTIL-TOC

mdast-util-toc

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

toc

✓ import { toc } from 'mdast-util-toc'

✗ const toc = require('mdast-util-toc')

mdast-util-toc is an ESM-only package since v6.0.0, requiring `import` syntax.

Options, Result

✓ import type { Options, Result } from 'mdast-util-toc'

Import TypeScript types for function options and return structures.

toc

✓ import {toc} from 'https://esm.sh/mdast-util-toc@7'

For browser and Deno environments, use an ESM CDN like esm.sh. The `@7` ensures the latest v7 version.

This example demonstrates how to import the `toc` function and use it to generate a table of contents from a simple mdast syntax tree, configured to include headings up to depth 2.

import {toc} from 'mdast-util-toc'; /** @type {import('mdast').Root} */ const tree = { type: 'root', children: [ {type: 'heading', depth: 1, children: [{type: 'text', value: 'Alpha'}]}, {type: 'heading', depth: 2, children: [{type: 'text', value: 'Bravo'}]}, {type: 'heading', depth: 3, children: [{type: 'text', value: 'Charlie'}]}, {type: 'heading', depth: 2, children: [{type: 'text', value: 'Delta'}]}, {type: 'paragraph', children: [{type: 'text', value: 'Some content here.'}]}, {type: 'heading', depth: 1, children: [{type: 'text', value: 'Gamma'}]} ] }; // Generate a table of contents for the entire tree const table = toc(tree, { maxDepth: 2 }); console.dir(table, {depth: 3}); /* Expected Output (simplified): { index: undefined, endIndex: undefined, map: { type: 'list', ordered: false, spread: true, children: [ { type: 'listItem', spread: true, children: [ [Object] ] }, // Alpha { type: 'listItem', spread: true, children: [ [Object], [Object] ] } // Gamma ] } } */

Debug

Known issues

breakingmdast-util-toc became an ESM-only package. CommonJS `require()` is no longer supported.

fix

Migrate your project to ESM and use `import { toc } from 'mdast-util-toc'`. If using Node.js, ensure your package.json has `"type": "module"` or files end in `.mjs`.

affects: >=6.0.0

breakingNode.js 16 or higher is now required to use mdast-util-toc.

fix

Upgrade your Node.js environment to version 16 or newer. Use a Node.js version manager like `nvm` to switch.

affects: >=7.0.0

breakingThe `toc` function now returns `undefined` if no table of contents can be generated (e.g., no headings found or no matching heading). Previously, it returned `null`.

fix

Update your code to expect `undefined` instead of `null` when checking for the absence of a TOC result, e.g., `if (table === undefined) { /* handle no TOC */ }`.

affects: >=7.0.0

gotchaThe package now uses an `export` map. Avoid using private or internal APIs as they might change without warning.

fix

Always use the documented public exports, such as `import { toc } from 'mdast-util-toc'`, and avoid deeply importing from internal paths like `mdast-util-toc/lib/some-internal-module`.

affects: >=7.0.0

gotchaThe `minDepth` option was added, allowing you to specify the minimum heading depth to include in the generated table of contents.

fix

Review your `toc` options. If you previously filtered headings by depth after generation, consider using the `minDepth` option (along with `maxDepth`) for more efficient, built-in filtering, e.g., `toc(tree, { minDepth: 2, maxDepth: 4 })`.

affects: >=7.1.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ...mdast-util-toc failed

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

fix

Change your import statement to `import { toc } from 'mdast-util-toc';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

TypeError: Cannot read properties of null (reading 'map')

Your code is expecting the `toc` function to return an object with a `map` property, but it received `null` (pre-v7 behavior) or `undefined` (v7+ behavior) because no table of contents could be generated.

fix

Before accessing properties like `map`, check if the `table` result is not `undefined` (or `null` for older versions): `const table = toc(tree); if (table && table.map) { /* process table */ }`

SyntaxError: Named export 'toc' not found. The requested module 'mdast-util-toc' does not provide an export named 'toc'

This typically occurs when trying to use ESM `import` syntax in an environment (like an older Node.js version) that doesn't fully support ESM, or when there's a module resolution issue.

fix

Ensure you are running Node.js 16+ and your project's `package.json` specifies `"type": "module"` if you are using `.js` files for ESM. Otherwise, use `.mjs` file extensions. Verify `mdast-util-toc` is correctly installed.

Upgrade

Version history

7.1.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-toc ↗

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