remark-lint-heading-style

4.0.1 verified Fri May 01 auth: no javascript

A remark-lint rule that warns when Markdown headings violate a specified or consistent style (ATX, ATX-closed, or setext). Version 4.0.1 is the latest stable release, part of the remark-lint ecosystem. It is ESM-only (Node 16+). Unlike alternatives like markdownlint, it integrates seamlessly with unified and remark, allowing programmatic linting and fixes. It supports automatic style detection (consistent) and explicit configuration. The package ships TypeScript types and is commonly used in presets like remark-preset-lint-consistent and remark-preset-lint-markdown-style-guide.

Common errors

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

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

fix

Use dynamic import() or switch to ES modules. Set 'type': 'module' in package.json.

error TypeError: remarkLintHeadingStyle is not a function ↓

cause Named import instead of default import.

fix

Use: import remarkLintHeadingStyle from 'remark-lint-heading-style'

error Cannot find module 'remark-lint' ↓

cause Missing peer dependency remark-lint.

fix

Install remark-lint alongside: npm install remark-lint remark-lint-heading-style

Warnings

breaking ESM-only since v4; requires Node 16+ and cannot be used with CommonJS require(). ↓

fix Switch to ES modules: use 'import' instead of 'require()'. Set type: 'module' in package.json or use .mjs extension.

deprecated The older style option 'consistent' is deprecated in favor of explicit style or 'consistent' string? Actually, 'consistent' is still valid but may change in future major versions. ↓

fix Use explicit style like 'atx' or 'setext' to be safe.

gotcha The rule only checks top-level headings; nested headings inside blockquotes or list items may not be linted consistently across all versions. ↓

fix Ensure the markdown structure is flat or test edge cases; consider using remark-lint with other plugins.

Install

npm install remark-lint-heading-style

yarn add remark-lint-heading-style

pnpm add remark-lint-heading-style

Imports

remarkLintHeadingStyle

wrong

import { remarkLintHeadingStyle } from 'remark-lint-heading-style'

correct

import remarkLintHeadingStyle from 'remark-lint-heading-style'

Default export only; named export will fail. ESM-only since v4.

Options

wrong

import { Options } from 'remark-lint-heading-style'

correct

import type { Options } from 'remark-lint-heading-style'

TypeScript type, not a runtime value; use import type.

Style
```
import type { Style } from 'remark-lint-heading-style'
```
TypeScript type; valid values: 'atx', 'atx-closed', 'setext'.

Quickstart

Demonstrates unified pipeline to parse, lint headings for ATX style, and output warnings using vfile-reporter.

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

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

await unified()
  .use(remarkParse)
  .use(remarkLint)
  .use(remarkLintHeadingStyle, 'atx') // or 'consistent' (default)
  .use(remarkStringify)
  .process(file)

console.error(reporter(file))