Getting started

madr-lint is a linter for MADR (Markdown Architectural Decision Records). It validates ADR structure, status values, dates, filenames, and cross-file integrity.

Install

Install it as a dev dependency:

# npm
npm install --save-dev madr-lint

# pnpm
pnpm add -D madr-lint

# yarn
yarn add -D madr-lint

Requires Node.js 22 or newer.

You can also run it without installing:

npx madr-lint --help

Run your first lint

By default madr-lint lints the directory configured as adrDir (default: docs/adr):

npx madr-lint

Or point it at explicit files or directories — directories are searched recursively for .md files:

npx madr-lint docs/adr docs/decisions/0007-use-x.md

Example output:

docs/adr/0003-use-postgres.md
  error  madr/status-enum        Status "decided" is not one of: proposed,rejected,accepted,deprecated,superseded by ...
  error  madr/required-sections  Missing required section: "Consequences"

2 errors

Enable the recommended rules

Out of the box, when no rules are configured, the CLI falls back to the madr-lint:recommended preset. To make that explicit — and to start customizing — create a config file:

madr-lint.config.ts

import { defineConfig } from 'madr-lint';

export default defineConfig({
  extends: ['madr-lint:recommended'],
  adrDir: 'docs/adr',
});

See Configuration for every option, and Rules for the full rule reference.

Exit codes

madr-lint is CI-friendly:

Exit code	Meaning
0	No errors (warnings may still be printed)
1	One or more error-severity diagnostics
2	Configuration problem (e.g. invalid rule options, unknown --format)

Next steps

• Configuration — config file, presets, and per-rule options
• CLI — every command-line flag
• GitHub Action — run it in CI
• Rules — what each rule checks and its options