remark-lint-heading-increment

4.0.1 verified Fri May 01 auth: no javascript

A remark-lint rule that warns when heading levels increase by more than one level at a time (e.g., from h1 to h3). This helps enforce accessible heading hierarchies as recommended by HTML accessibility guidelines, where headings should increment by one level. Part of the remark-lint ecosystem, current stable version is 4.0.1 (ESM-only since v2, ships TypeScript types). Released as part of the remark-lint monorepo with regular updates. No options needed. Integrates with remark-lint presets like remark-preset-lint-markdown-style-guide.

Common errors

error Unexpected heading rank `3`, exected rank `2` ↓

cause Heading level jumped from h1 to h3 without an h2 in between.

fix

Insert an h2 heading between the h1 and h3, or adjust heading levels to increment by one.

error remark-lint-heading-increment is not a function ↓

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

fix

Use import remarkLintHeadingIncrement from 'remark-lint-heading-increment' or set "type": "module" in package.json.

error ERR_MODULE_NOT_FOUND ↓

cause Missing dependencies or incorrect import path.

fix

Ensure remark-lint, unified, remark-parse, etc. are installed. Check that the import path is exactly 'remark-lint-heading-increment'.

Warnings

breaking Package is ESM-only; CommonJS require() will fail ↓

fix Use import or dynamic import() instead of require().

deprecated The option 'style' was removed in v3.0.0 ↓

fix Remove any 'style' option; this rule now has no options.

gotcha When using with remark-preset-lint-markdown-style-guide, the preset may already include this rule, causing duplicate warnings ↓

fix Do not add the rule manually if the preset is used; check preset documentation.

breaking TypeScript types changed in v4.0.0 (refactored internal types for option coercion) ↓

fix If using TypeScript, ensure your project uses @import syntax and upgrade remark-lint types if needed.

gotcha This rule only works on headings; it does not detect jumps in nested lists or other structures ↓

fix Combine with other lint rules if needed to enforce consistent structure.

Install

npm install remark-lint-heading-increment

yarn add remark-lint-heading-increment

pnpm add remark-lint-heading-increment

Imports

remarkLintHeadingIncrement
wrong
```
const { remarkLintHeadingIncrement } = require('remark-lint-heading-increment')
```
correct
```
import remarkLintHeadingIncrement from 'remark-lint-heading-increment'
```
This package is ESM-only. Default export. CommonJS require is not supported. The function is used as a plugin: .use(remarkLintHeadingIncrement).
remarkLint
wrong
```
const remarkLint = require('remark-lint')
```
correct
```
import remarkLint from 'remark-lint'
```
The remark-lint package is also ESM-only. Must be imported and used before individual lint rules.
unified
wrong
```
const unified = require('unified')
```
correct
```
import { unified } from 'unified'
```
unified package is ESM-only since v10. Use named import.

Quickstart

Shows how to use remark-lint-heading-increment to lint a Markdown file for heading level jumps, outputting any warnings.

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import remarkLint from 'remark-lint'
import remarkLintHeadingIncrement from 'remark-lint-heading-increment'
import { read } from 'to-vfile'
import { reporter } from 'vfile-reporter'

const file = await read('example.md')

await unified()
  .use(remarkParse)
  .use(remarkLint)
  .use(remarkLintHeadingIncrement)
  .use(remarkStringify)
  .process(file)

console.error(reporter(file))