Registry / testing / remark-lint-no-multiple-toplevel-headings

remark-lint-no-multiple-toplevel-headings

library4.0.1jsnpmunverified

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.

testing web-framework

npm install remark-lint-no-multiple-toplevel-headings

github ↗package ↗

INSTALL

IMPORT

SIG · REMARK-LINT-NO-MUL

remark-lint-no-multiple-toplevel-headings

testingjavascriptv4.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

remarkLintNoMultipleToplevelHeadings

✓ import remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings'

✗ const {remarkLintNoMultipleToplevelHeadings} = require('remark-lint-no-multiple-toplevel-headings')

ESM-only since v4; no default export in CJS. The package exports only the function as default.

Depth

✓ import type {Depth} from 'remark-lint-no-multiple-toplevel-headings'

✗ import {Depth} from 'remark-lint-no-multiple-toplevel-headings'

TypeScript type export, not a runtime value. Only needed for type annotations.

Options

✓ import type {Options} from 'remark-lint-no-multiple-toplevel-headings'

✗ const Options = require('remark-lint-no-multiple-toplevel-headings').Options

TypeScript type export; not a constructor or function. Use for option typing.

Shows how to use the rule with unified, linting for duplicate level-2 headings.

import {unified} from 'unified'; import remarkParse from 'remark-parse'; import remarkStringify from 'remark-stringify'; import remarkLint from 'remark-lint'; import remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings'; import {reporter} from 'vfile-reporter'; const file = await unified() .use(remarkParse) .use(remarkLint) .use(remarkLintNoMultipleToplevelHeadings, 2) // warn if multiple headings of rank 2 .use(remarkStringify) .process('# Hello\n\n## World\n\n## Again'); console.error(reporter(file)); // Expected: 3:1-3:9: Unexpected duplicate toplevel heading, expected a single heading with rank `2`

Debug

Known issues

breakingPackage is ESM-only since v4. Calling require() will fail.

fix

Use import syntax or switch to dynamic import(). For CommonJS projects, consider using remark-lint-no-multiple-toplevel-headings@3 (last CJS version).

affects: >=4.0.0

deprecatedThe options type changed in v4: now accepts Depth (1–6) directly, previously accepted an object with `depth` property.

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

affects: <4.0.0

breakingPeer dependency on remark-lint must be >=10. Using with older versions may cause runtime errors.

fix

Upgrade remark-lint to >=10. Run `npm install remark-lint@latest`.

affects: >=4.0.0

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

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.

affects: >=1.0.0

deprecatedThe `depth` option as object property (e.g., `{depth: 1}`) is deprecated in v4 and ignored silently.

fix

Pass the depth number directly: `.use(remarkLintNoMultipleToplevelHeadings, 1)`.

affects: >=4.0.0

Errors

Common errors & fixes

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.

Used require() on an ESM-only package (v4+).

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

TypeError: (0 , _remarkLintNoMultipleToplevelHeadings.default) is not a function

Using default export incorrectly in a CJS environment or mixing import styles.

fix

Use the import statement as shown in the documentation: `import remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings'`.

Cannot read properties of undefined (reading 'type')

Using the rule without first running `remark-lint` plugin (the pipeline requires `remarkLint` to be registered).

fix

Add `.use(remarkLint)` before `.use(remarkLintNoMultipleToplevelHeadings)` in the unified chain.

Unexpected duplicate toplevel heading, expected a single heading with rank `1` but got 2

Document has multiple level-1 headings (default depth=1).

fix

Change the extra top-level headings to a lower rank (e.g., `##`), or configure a different depth via options.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

remark-lintoptionalpeer dependency; the linting framework that runs this rule

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/remarkjs/remark-lint.git#main ↗

packagehttps://www.npmjs.com/package/remark-lint-no-multiple-toplevel-headings ↗