Skip to content

markdownlint-cli2.md

Latest commit

 

History

History
195 lines (127 loc) · 3.77 KB

markdownlint-cli2.md

File metadata and controls

195 lines (127 loc) · 3.77 KB
Raw

markdownlint-cli2

markdownlint-cli2 validates Markdown files against configurable style and structure rules.

It helps keep the repository documentation consistent as the number of Markdown files grows.

The tool is installed through Homebrew and declared in the project Brewfile.

Installation

It is part of the curated Homebrew environment; see Homebrew setup to install everything at once.

Install markdownlint-cli2 directly:

brew install markdownlint-cli2

Verify the installation:

markdownlint-cli2 --version
brew list --formula | grep -x markdownlint-cli2

Repository configuration

The repository configuration is declared in:

.markdownlint-cli2.yaml

Current configuration:

config:
  MD013: false

The MD013 line-length rule is disabled because enforcing an 80-character limit would make the documentation unnecessarily difficult to maintain.

Other Markdown rules remain enabled.

Running the checks

Check all Markdown files:

markdownlint-cli2 "**/*.md"

Check selected files:

markdownlint-cli2 README.md docs/**/*.md

markdownlint-cli2 checking README and documentation files with zero errors

Apply supported automatic fixes:

markdownlint-cli2 --fix "**/*.md"

Automatic fixes should be reviewed before being committed.

Pre-commit integration

The repository runs markdownlint-cli2 through pre-commit.

The hook is configured as a local system hook:

- id: markdownlint-cli2
  name: markdownlint-cli2
  entry: markdownlint-cli2
  language: system
  types: [markdown]

Run only this hook:

pre-commit run markdownlint-cli2 --all-files

Common rules

markdownlint can detect issues such as:

  • inconsistent heading levels;
  • missing blank lines around lists or headings;
  • repeated blank lines;
  • malformed fenced code blocks;
  • inconsistent list markers;
  • missing language identifiers on code fences;
  • trailing punctuation or spacing problems.

The exact active rules depend on the repository configuration.

Fixing errors

Run the checker and review the reported file and line number:

markdownlint-cli2 "**/*.md"

For automatically fixable issues:

markdownlint-cli2 --fix "**/*.md"

Then inspect the changes:

git diff

Do not disable a rule globally when a local documentation issue can be fixed cleanly.

Configuration changes

Any rule change should be:

  1. motivated by the repository's actual writing style;
  2. applied narrowly;
  3. documented when it affects contributors;
  4. tested against all Markdown files.

Avoid disabling multiple rules simply to make the checker pass.

Relationship with lychee

markdownlint-cli2 validates Markdown structure and style.

Lychee validates links found inside Markdown files.

Both tools are complementary:

markdownlint-cli2 "**/*.md"
lychee README.md 'docs/**/*.md'

Troubleshooting

Display the available options:

markdownlint-cli2 --help

Confirm the executable path:

command -v markdownlint-cli2

Validate only the repository README:

markdownlint-cli2 README.md

If a configuration change is not applied, confirm that .markdownlint-cli2.yaml exists at the repository root.

After an update, rerun the complete documentation check because new rules or rule behavior may be introduced.

Rollback

Remove markdownlint-cli2 with Homebrew:

brew uninstall markdownlint-cli2

Then remove:

  • its entry from profiles/full/Brewfile;
  • its hook from .pre-commit-config.yaml;
  • .markdownlint-cli2.yaml if no other Markdown tooling uses it.

← Docs index · Project README