remark-lint-no-duplicate-headings

4.0.1 verified Fri May 01 auth: no javascript

remark-lint rule to warn when headings with equivalent text appear in a Markdown document. Current stable version is 4.0.1. Part of the remark-lint ecosystem, this plugin is ESM-only, requires Node.js 16+, and is included in the `remark-preset-lint-markdown-style-guide` preset. It helps screen reader users and prevents fragile automatic heading IDs. Unlike custom checks, it integrates directly with unified pipelines and CLI.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module ↓

cause Using CommonJS require() on an ESM-only package.

fix

Switch to ESM imports or use dynamic import().

error TypeError: (0 , remarkLintNoDuplicateHeadings) is not a function ↓

cause Importing named export instead of default.

fix

Use import remarkLintNoDuplicateHeadings from 'remark-lint-no-duplicate-headings'.

Warnings

breaking Package is ESM-only since v3; CommonJS require() will throw. ↓

fix Use import syntax or dynamic import().

gotcha Plugin accepts no options; attempting to pass options will be ignored. ↓

fix Remove any options object from .use(remarkLintNoDuplicateHeadings).

gotcha Comparison is case-sensitive and includes leading/trailing whitespace; headings that differ only in case or whitespace are not flagged. ↓

fix Ensure exact text match for detection.

Install

npm install remark-lint-no-duplicate-headings

yarn add remark-lint-no-duplicate-headings

pnpm add remark-lint-no-duplicate-headings

Imports

remarkLintNoDuplicateHeadings

wrong

const remarkLintNoDuplicateHeadings = require('remark-lint-no-duplicate-headings')

correct

import remarkLintNoDuplicateHeadings from 'remark-lint-no-duplicate-headings'

Package is ESM-only since v3; CommonJS require will fail.

remarkLintNoDuplicateHeadings

wrong

import { remarkLintNoDuplicateHeadings } from 'remark-lint-no-duplicate-headings'

correct

import remarkLintNoDuplicateHeadings from 'remark-lint-no-duplicate-headings'

Default export, not named.

Type definitions

wrong

Attempting to import types separately like `import type { Options } from 'remark-lint-no-duplicate-headings'`

correct

No type imports needed; types are shipped with package.

The plugin accepts no options, so no types are exported.

Quickstart

Runs linting on example.md, reporting duplicate headings. ESM-only, Node 16+.

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import remarkLint from 'remark-lint'
import remarkLintNoDuplicateHeadings from 'remark-lint-no-duplicate-headings'
import { read } from 'to-vfile'
import { reporter } from 'vfile-reporter'

const file = await unified()
  .use(remarkParse)
  .use(remarkLint)
  .use(remarkLintNoDuplicateHeadings)
  .use(remarkStringify)
  .process(await read('example.md'))

console.error(reporter(file))