{"id":26266,"library":"remark-lint-no-multiple-toplevel-headings","title":"remark-lint-no-multiple-toplevel-headings","description":"A remark-lint rule that warns when multiple top-level headings (rank 1) are used in a Markdown document. Current stable version is 4.0.1. This package is part of the remark-lint ecosystem, with releases typically following semantic versioning on a monthly cadence. It differs from other heading‐duplicate checks by focusing specifically on the primary heading level, often used in presets like `remark-preset-lint-markdown-style-guide`. It supports custom depth configuration (1–6) via options. ESM-only, with TypeScript types included. Version 4.x requires remark-lint >=10 and Node >=16.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/remarkjs/remark-lint#main","tags":["javascript","heading","lint","remark","remark-lint","remark-lint-rule","rule","top-level","typescript"],"install":[{"cmd":"npm install remark-lint-no-multiple-toplevel-headings","lang":"bash","label":"npm"},{"cmd":"yarn add remark-lint-no-multiple-toplevel-headings","lang":"bash","label":"yarn"},{"cmd":"pnpm add remark-lint-no-multiple-toplevel-headings","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency; the linting framework that runs this rule","package":"remark-lint","optional":true}],"imports":[{"note":"ESM-only since v4; no default export in CJS. The package exports only the function as default.","wrong":"const {remarkLintNoMultipleToplevelHeadings} = require('remark-lint-no-multiple-toplevel-headings')","symbol":"remarkLintNoMultipleToplevelHeadings","correct":"import remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings'"},{"note":"TypeScript type export, not a runtime value. Only needed for type annotations.","wrong":"import {Depth} from 'remark-lint-no-multiple-toplevel-headings'","symbol":"Depth","correct":"import type {Depth} from 'remark-lint-no-multiple-toplevel-headings'"},{"note":"TypeScript type export; not a constructor or function. Use for option typing.","wrong":"const Options = require('remark-lint-no-multiple-toplevel-headings').Options","symbol":"Options","correct":"import type {Options} from 'remark-lint-no-multiple-toplevel-headings'"}],"quickstart":{"code":"import {unified} from 'unified';\nimport remarkParse from 'remark-parse';\nimport remarkStringify from 'remark-stringify';\nimport remarkLint from 'remark-lint';\nimport remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings';\nimport {reporter} from 'vfile-reporter';\n\nconst file = await unified()\n  .use(remarkParse)\n  .use(remarkLint)\n  .use(remarkLintNoMultipleToplevelHeadings, 2) // warn if multiple headings of rank 2\n  .use(remarkStringify)\n  .process('# Hello\\n\\n## World\\n\\n## Again');\n\nconsole.error(reporter(file));\n// Expected: 3:1-3:9: Unexpected duplicate toplevel heading, expected a single heading with rank `2`","lang":"typescript","description":"Shows how to use the rule with unified, linting for duplicate level-2 headings."},"warnings":[{"fix":"Use import syntax or switch to dynamic import(). For CommonJS projects, consider using remark-lint-no-multiple-toplevel-headings@3 (last CJS version).","message":"Package is ESM-only since v4. Calling require() will fail.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update call from `.use(rule, {depth: 1})` to `.use(rule, 1)`. If using previous object form, it is silently ignored in v4 (produces no linting).","message":"The options type changed in v4: now accepts Depth (1–6) directly, previously accepted an object with `depth` property.","severity":"deprecated","affected_versions":"<4.0.0"},{"fix":"Upgrade remark-lint to >=10. Run `npm install remark-lint@latest`.","message":"Peer dependency on remark-lint must be >=10. Using with older versions may cause runtime errors.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use `.use(remarkLintNoMultipleToplevelHeadings, 2)` for level-2 headings, etc. Or use a different rule (e.g., `remark-lint-no-duplicate-headings`) for hierarchical duplicates.","message":"The rule only checks for duplicate *top-level* headings (configurable depth default 1). If you want to check other levels, you must pass an explicit depth option. It does not check for duplicate headings at lower levels.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass the depth number directly: `.use(remarkLintNoMultipleToplevelHeadings, 1)`.","message":"The `depth` option as object property (e.g., `{depth: 1}`) is deprecated in v4 and ignored silently.","severity":"deprecated","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use `import remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings'` in an ESM context, or downgrade to v3 with `npm install remark-lint-no-multiple-toplevel-headings@3`.","cause":"Used require() on an ESM-only package (v4+).","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/remark-lint-no-multiple-toplevel-headings/index.js from /path/to/project/script.js not supported."},{"fix":"Use the import statement as shown in the documentation: `import remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings'`.","cause":"Using default export incorrectly in a CJS environment or mixing import styles.","error":"TypeError: (0 , _remarkLintNoMultipleToplevelHeadings.default) is not a function"},{"fix":"Add `.use(remarkLint)` before `.use(remarkLintNoMultipleToplevelHeadings)` in the unified chain.","cause":"Using the rule without first running `remark-lint` plugin (the pipeline requires `remarkLint` to be registered).","error":"Cannot read properties of undefined (reading 'type')"},{"fix":"Change the extra top-level headings to a lower rank (e.g., `##`), or configure a different depth via options.","cause":"Document has multiple level-1 headings (default depth=1).","error":"Unexpected duplicate toplevel heading, expected a single heading with rank `1` but got 2"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}