remark-lint-no-multiple-toplevel-headings

4.0.1 verified Fri May 01 auth: no javascript

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.

Common errors

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

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

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

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

error Cannot read properties of undefined (reading 'type') ↓

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

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

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

Warnings

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

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

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

gotcha 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. ↓

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.

deprecated The `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)`.

Install

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

yarn add remark-lint-no-multiple-toplevel-headings

pnpm add remark-lint-no-multiple-toplevel-headings

Imports

remarkLintNoMultipleToplevelHeadings

wrong

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

correct

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

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

Depth

wrong

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

correct

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

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

Options

wrong

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

correct

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

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

Quickstart

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`