@dnbhq/markdownlint-config

Shared markdownlint-cli2 configuration for DNBHQ projects.

• Installation
• Usage
• Available files
• Rule overview
  • Baseline behaviour
  • Heading rules
  • List rules
  • Line length and prose rules
  • HTML and media rules
  • Code and emphasis rules
  • Link and table rules
  • Horizontal rule rules
  • Search and typography rules
• Release
• Notes

Installation

npm install --save-dev @dnbhq/markdownlint-config

The package installs everything required to run markdownlint through markdownlint-cli2:

• markdownlint-cli2
• markdownlint
• @github/markdownlint-github
• markdownlint-rule-extended-ascii
• markdownlint-rule-relative-links
• markdownlint-rule-search-replace
• markdownlint-rule-title-case-style

Consuming projects do not need to install those packages separately.

Usage

This package is designed for markdownlint-cli2, not the older markdownlint CLI.

Run this configuration with the following call:

npx markdownlint-cli2 --config ./node_modules/@dnbhq/markdownlint-config/.markdownlint-cli2.jsonc README.md

Add scripts to package.json in the consuming project:

{
  "scripts": {
    "lint:markdown": "markdownlint-cli2 --config ./node_modules/@dnbhq/markdownlint-config/.markdownlint-cli2.jsonc \"**/*.{md,mdx}\"",
    "lint:markdown:fix": "markdownlint-cli2 --config ./node_modules/@dnbhq/markdownlint-config/.markdownlint-cli2.jsonc --fix \"**/*.{md,mdx}\""
  }
}

Do not put a markdownlint-cli2 options object into .markdownlint.jsonc. That file name is treated as a markdownlint rule configuration only. If a project needs CLI2-only fields such as customRules, globs, or ignores, use .markdownlint-cli2.jsonc.

The package also ships .markdownlintignore. Copy it into a consuming project when that project wants to use the same ignore baseline.

Available files

The npm package publishes these files:

• .markdownlint-cli2.jsonc - the shared markdownlint-cli2 configuration.
• rules/*.cjs - custom rule loader wrappers used by markdownlint-cli2.
• .markdownlintignore - the shared ignore baseline.
• README.md - package documentation.
• CHANGELOG.md - release history generated by release-it.
• LICENSE - MIT licence.

Rule overview

Baseline behaviour

The shared rule config enables markdownlint defaults with default: true and then overrides selected rules for DNBHQ projects.

Heading rules

• MD001 enforces heading increments and recognises frontmatter titles via title: or title=.
• MD003 requires ATX headings with # markers.
• MD020 and MD021 are disabled because closed ATX headings are not used.
• MD024 disallows duplicate headings among siblings while allowing the same heading text in different nesting branches.
• MD043 is disabled because projects do not share one fixed heading structure.

List rules

• MD004 requires * as the unordered list marker.
• MD005 keeps indentation consistent for list items at the same level.
• MD007 uses two spaces for nested list indentation.

Line length and prose rules

• MD013 is disabled, so prose line length is unrestricted.
• MD044 is disabled, so markdownlint does not enforce a fixed proper-name spelling list.
• MD059 rejects generic link text: click here, here, link, and more.
• GH002 adds GitHub-style generic link-text checks with Something and Click here as additional banned text.

HTML and media rules

• MD033 rejects inline HTML except lite-youtube, color-grid, date-diff, and kbd.
• Inside tables, MD033 allows only kbd.
• GH001 rejects default image alt text.
• GH003 rejects empty image alt text.

Code and emphasis rules

• MD046 requires fenced code blocks.
• MD048 requires backtick fences instead of tilde fences.
• MD049 requires * for emphasis.
• MD050 requires ** for strong text.

Link and table rules

• MD054 disallows autolinks.
• MD055 requires leading and trailing pipes for table rows.
• MD060 requires compact table cell spacing.
• markdownlint-rule-relative-links checks relative links. The shared config uses root_path: "." because consuming repositories can have different folder layouts.

Horizontal rule rules

• MD035 requires --- when horizontal rules are used.

This only standardises the marker style. It does not mean horizontal rules should be used as visual separators in documentation.

Search and typography rules

markdownlint-rule-search-replace adds two checks:

• ellipsis flags three literal dots in prose.
• curly-double-quotes flags curly double quotation marks and suggests straight double quotation marks.

markdownlint-rule-extended-ascii enforces ASCII-only Markdown content.

markdownlint-rule-title-case-style requires sentence case for headings and ignores JavaScript as an allowed spelling.

Release

Dry run:

npm run release:dry

Release:

npm run release

Releases are handled by release-it and @release-it/conventional-changelog.

Commit messages should follow Conventional Commits.

Publishing is handled by the Publish package GitHub Actions workflow when a v* tag is pushed. The workflow verifies that the tag matches package.json, runs the package tests, and publishes to npm.

Notes

• Consumers install only @dnbhq/markdownlint-config; the package carries markdownlint-cli2, markdownlint, and all custom rules as direct dependencies.
• config.jsonc is a markdownlint-cli2 configuration file.
• rules.jsonc is a markdownlint rule configuration file.
• Use .markdownlint-cli2.jsonc in consuming projects whenever CLI2-only options such as customRules, globs, or ignores are needed.
• The repository test command currently runs markdownlint-cli2 against this README with the shared config.