{"id":11293,"library":"mdast-util-toc","title":"mdast-util-toc: Markdown Table of Contents Utility","description":"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.","status":"active","version":"7.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-util-toc","tags":["javascript","unist","mdast","mdast-util","util","utility","markdown","table","contents","typescript"],"install":[{"cmd":"npm install mdast-util-toc","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-util-toc","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-util-toc","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"mdast-util-toc is an ESM-only package since v6.0.0, requiring `import` syntax.","wrong":"const toc = require('mdast-util-toc')","symbol":"toc","correct":"import { toc } from 'mdast-util-toc'"},{"note":"Import TypeScript types for function options and return structures.","symbol":"Options, Result","correct":"import type { Options, Result } from 'mdast-util-toc'"},{"note":"For browser and Deno environments, use an ESM CDN like esm.sh. The `@7` ensures the latest v7 version.","symbol":"toc","correct":"import {toc} from 'https://esm.sh/mdast-util-toc@7'"}],"quickstart":{"code":"import {toc} from 'mdast-util-toc';\n\n/** @type {import('mdast').Root} */\nconst tree = {\n  type: 'root',\n  children: [\n    {type: 'heading', depth: 1, children: [{type: 'text', value: 'Alpha'}]},\n    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Bravo'}]},\n    {type: 'heading', depth: 3, children: [{type: 'text', value: 'Charlie'}]},\n    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Delta'}]},\n    {type: 'paragraph', children: [{type: 'text', value: 'Some content here.'}]},\n    {type: 'heading', depth: 1, children: [{type: 'text', value: 'Gamma'}]}\n  ]\n};\n\n// Generate a table of contents for the entire tree\nconst table = toc(tree, { maxDepth: 2 });\n\nconsole.dir(table, {depth: 3});\n\n/* Expected Output (simplified):\n{\n  index: undefined,\n  endIndex: undefined,\n  map: {\n    type: 'list',\n    ordered: false,\n    spread: true,\n    children: [\n      { type: 'listItem', spread: true, children: [ [Object] ] }, // Alpha\n      { type: 'listItem', spread: true, children: [ [Object], [Object] ] } // Gamma\n    ]\n  }\n}\n*/","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"mdast-util-toc became an ESM-only package. CommonJS `require()` is no longer supported.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Upgrade your Node.js environment to version 16 or newer. Use a Node.js version manager like `nvm` to switch.","message":"Node.js 16 or higher is now required to use mdast-util-toc.","severity":"breaking","affected_versions":">=7.0.0"},{"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 */ }`.","message":"The `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`.","severity":"breaking","affected_versions":">=7.0.0"},{"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`.","message":"The package now uses an `export` map. Avoid using private or internal APIs as they might change without warning.","severity":"gotcha","affected_versions":">=7.0.0"},{"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 })`.","message":"The `minDepth` option was added, allowing you to specify the minimum heading depth to include in the generated table of contents.","severity":"gotcha","affected_versions":">=7.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` to import an ESM-only package.","error":"ERR_REQUIRE_ESM: require() of ES Module ...mdast-util-toc failed"},{"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 */ }`","cause":"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.","error":"TypeError: Cannot read properties of null (reading 'map')"},{"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.","cause":"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.","error":"SyntaxError: Named export 'toc' not found. The requested module 'mdast-util-toc' does not provide an export named 'toc'"}],"ecosystem":"npm"}