markdownlint-styleguide

Custom markdownlint rules that enforce sentence-case headings, backtick code elements, proper link formatting, and prose style — with a three-tier autofix system that applies safe fixes automatically and flags ambiguous cases for review.

# Getting Started With Our API                          ← before
Install the package using npm install my-package.
Visit https://example.com for docs & tutorials.

# Getting started with our API                          ← after
Install the package using `npm install my-package`.
Visit [our documentation](https://example.com) for docs and tutorials.

Quick start

Important

Requires Node.js 24+ (>=24.16.0) and npm.

npm install -D github:kynoptic/markdownlint-styleguide markdownlint-cli2
npx mdsg init --preset recommended --all

This configures CLI, VS Code integration, CI workflow, npm scripts, and pre-commit hooks. Then:

npm run lint:md          # check for issues
npm run lint:md:fix      # auto-fix issues

For a lighter setup without CI or hooks:

npm install -D github:kynoptic/markdownlint-styleguide markdownlint-cli2
npx mdsg init --preset recommended
npx markdownlint-cli2 "**/*.md"

The generated config includes "gitignore": true, so markdownlint-cli2 automatically skips node_modules and any other paths listed in .gitignore.

Rules

Rule	ID	Auto-fix	Purpose
sentence-case-heading	SC001	Yes	Enforces sentence case for headings
backtick-code-elements	BCE001	Yes	Wraps code elements in backticks
no-bare-url	BU001	Yes	Prevents bare URLs in content
no-dead-internal-links	DL001	No	Detects broken internal links
no-literal-ampersand	NLA001	Yes	Replaces & with "and"
no-empty-list-items	ELI001	Yes	Flags empty or whitespace-only list items
date-time-consistency	DTC001	Yes	Validate weekdays, EST/EDT, and UTC offsets against the date

Auto-fixes use confidence scoring: high-confidence fixes apply automatically, ambiguous cases are flagged for review, and uncertain changes are skipped. See rules reference for full details.

Configuration

Three presets are available: basic, recommended, and strict. Override individual rules in .markdownlint-cli2.jsonc:

{
  "config": {
    "extends": "markdownlint-styleguide/recommended-config.jsonc",
    "no-literal-ampersand": false
  }
}

See configuration guide for presets, setup wizard options, and manual setup. Run npx mdsg doctor to verify your setup.

Documentation

The documentation index routes to setup, configuration, the rule catalogue, architecture, testing, and the architecture decision records.

Contributing

See the contributing guide for development setup, workflow, and guidelines.

License

MIT