Linting

This documentation site uses markdownlint-cli2 to enforce consistent Markdown style across all docs and blog posts.

Rules

The linting configuration lives in .markdownlint-cli2.jsonc at the root of the repository. The active rules are:

Rule	Setting	Description
default	true	All default markdownlint rules are enabled unless overridden below.
heading-increment	true	Headings must increment by one level at a time (no skipping).
MD007	indent: 2	Unordered list indentation must use 2 spaces.
MD013	line_length: 150, code blocks & tables excluded	Lines must not exceed 150 characters (code blocks and tables are exempt).
MD041	false	The first line of a file is not required to be a top-level heading (disabled to allow front matter).
no_toc	true	Inline table-of-contents markers are not allowed.

Scoped files

Linting applies to all *.md and *.mdx files inside the docs/ and blog/ directories.

Running the linter

Two npm scripts are available:

# Check for linting violations
npm run lint

# Automatically fix violations where possible
npm run lint:fix

Both scripts invoke markdownlint-cli2 under the hood. The lint:fix variant will auto-correct issues that have a safe automatic fix (such as trailing whitespace or list indentation), but some violations must be resolved manually.

VS Code extension

Install the Markdownlint extension (DavidAnson.vscode-markdownlint) to get real-time feedback directly in the editor.

With the extension installed:

• Violations are underlined in the editor as you type.
• Hovering over an underlined item shows the rule name and a description.
• Many issues can be fixed with the Quick Fix action (Ctrl+. / Cmd+.).
• The extension automatically picks up the .markdownlint-cli2.jsonc config from the workspace root, so the rules are identical to what the CLI enforces in CI.

info

Format on Save (editor.formatOnSave) is enabled in .vscode/settings.json so that auto-fixable issues are corrected every time you save a file.