Markdown docs with markdownlint and offline link checks

# AGENTS.md: Markdown docs that stay correct

This repository keeps its documentation in Markdown: the root README and pages under `docs/`. Docs are reviewed
like code: links, anchors and commands must be right, not just readable.

## Commands

- Style: `npx markdownlint-cli2` (config in `.markdownlint-cli2.jsonc`).
- Links, anchors and script commands: `node .agents/skills/docs-check/scripts/check_docs.mjs` (offline).
- Done means: both are clean.

## Rules

- Use the `docs-check` skill whenever you add or edit Markdown.
- Every command in the docs is one you ran or copied from `package.json`. Never invent a script, flag or
  environment variable.
- Fenced code blocks name their language.
- When a heading or file is renamed, fix every link to it in the same change.
- Relative links between docs pages. External links only to official or primary sources.
- Do not add markdownlint disable comments to get a clean run.
- Keep the README short: what it is, quick start, where the docs are. Detail goes in `docs/`.

# CLAUDE.md

@AGENTS.md

## Claude Code notes

- Skills from this loadout live in `.claude/skills/`: `docs-check`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Markdown docs with markdownlint and offline link checks" v1.0.0 — https://loadout.jnw-it.com/loadouts/docs-markdown-checks/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes

- Skills from this loadout live in `.agents/skills/`: `docs-check`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Markdown docs with markdownlint and offline link checks" v1.0.0 — https://loadout.jnw-it.com/loadouts/docs-markdown-checks/ -->

---
name: docs-check
description: Check Markdown docs before calling a docs change done - markdownlint-cli2 for style, and an offline check that relative links, images and #anchors resolve and that npm run commands in the docs exist. Use when writing or editing README files, docs/ pages, or anything that links between Markdown files.
---

# Docs check

Agents write docs that read well and are wrong in small ways: a link to a page that was renamed, an anchor
that no longer matches its heading, `npm run deploy` when there is no deploy script. Two checks catch these
without the network.

## Run both

```bash
npx markdownlint-cli2                                         # style; config in .markdownlint-cli2.jsonc
node .agents/skills/docs-check/scripts/check_docs.mjs         # links, anchors, script commands
```

`check_docs.mjs` takes paths (files or folders); with none it checks the root README and `docs/`.
Output is `file:line: problem` and a summary line; exit 1 means fix before finishing.

## What check_docs.mjs checks

- Relative links, images and reference definitions point at files that exist. A leading `/` means the
  repository root.
- A `#fragment` matches a heading in the target file, using GitHub's slug rules: lower case, punctuation
  dropped, spaces to hyphens, `-1`, `-2` for repeated headings. Explicit `<a id="...">` anchors count too.
- Every `npm run`, `pnpm run`, `yarn run` or `bun run` command in a code block or inline code names a script
  in the nearest `package.json`.
- External URLs are not fetched. Leave those to a scheduled link checker so a flaky site never blocks a change.

## Markdownlint config

Start from `references/markdownlint-cli2.jsonc` (copy it to the repository root as
`.markdownlint-cli2.jsonc`). It keeps the defaults and adds:

- MD040: every fenced block names its language (`bash`, `json`, `text` ...), so readers and highlighters know
  what it is.
- MD051: link fragments in the same file must match a heading.
- MD013 off (no hard wrapping of prose), MD024 only for sibling headings, a small HTML allow-list.

## Writing rules

- Commands in docs are commands you ran. Copy them from `package.json` scripts or your terminal, not memory.
- When you rename a heading or move a file, search for links to it (`rg -n 'old-slug|old-file.md'`) and fix
  them in the same change.
- Link with relative paths between docs files, never to the rendered GitHub URL of the same repository.
- Do not disable a markdownlint rule inline to get a clean run. Fix the Markdown, or change the shared config
  with a reason in the pull request.

## Done means

Both commands are clean, and the summary line from `check_docs.mjs` is in your report.

#!/usr/bin/env node
// Offline docs check for Markdown: relative links and images resolve, #fragments match a heading
// (GitHub-style slugs, including in other files), and `npm run <script>` style commands exist in package.json.
// No network: external URLs are left to a scheduled link checker.
//
//   node check_docs.mjs [paths...]     default: README.md and docs/ (when present)
// Exit 0 when clean, 1 when there are problems.
import fs from "node:fs";
import path from "node:path";

const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "vendor", ".venv"]);
const args = process.argv.slice(2);
const roots = args.length ? args : ["README.md", "docs"].filter((p) => fs.existsSync(p));

function walk(p, out) {
  const st = fs.statSync(p);
  if (st.isDirectory()) {
    for (const e of fs.readdirSync(p)) if (!SKIP_DIRS.has(e)) walk(path.join(p, e), out);
  } else if (/\.mdx?$/i.test(p)) out.push(path.normalize(p));
  return out;
}
const files = roots.flatMap((r) => (fs.existsSync(r) ? walk(r, []) : (console.log(`${r}: not found`), process.exitCode = 1, [])));

// Strip inline Markdown from a heading, then slug it the way GitHub does.
function slug(text) {
  return text
    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
    .replace(/`([^`]*)`/g, "$1")
    .replace(/<[^>]+>/g, "")
    .replace(/[*_~]{1,3}(\S[^*_~]*?)[*_~]{1,3}/g, "$1")
    .trim()
    .toLowerCase()
    .replace(/[^\p{L}\p{N}\p{M}\s_-]/gu, "")
    .replace(/\s/g, "-");
}

// Lines outside fenced code blocks, plus the fenced blocks themselves (for command checks).
function parse(file) {
  const lines = fs.readFileSync(file, "utf8").split(/\r?\n/);
  const prose = [];
  const code = [];
  let fence = null;
  lines.forEach((line, i) => {
    const m = line.match(/^\s{0,3}(`{3,}|~{3,})/);
    if (m && !fence) { fence = m[1]; return; }
    if (fence && line.trim().startsWith(fence)) { fence = null; return; }
    (fence ? code : prose).push({ n: i + 1, text: line });
  });
  return { prose, code };
}

const anchorCache = new Map();
function anchors(file) {
  if (anchorCache.has(file)) return anchorCache.get(file);
  const set = new Set();
  const seen = new Map();
  for (const { text } of parse(file).prose) {
    const h = text.match(/^\s{0,3}#{1,6}\s+(.*?)\s*#*\s*$/);
    for (const m of text.matchAll(/<a\s+(?:name|id)="([^"]+)"/g)) set.add(m[1]);
    if (!h) continue;
    const base = slug(h[1]);
    const count = seen.get(base) ?? 0;
    seen.set(base, count + 1);
    set.add(count ? `${base}-${count}` : base);
  }
  anchorCache.set(file, set);
  return set;
}

function nearestPackageJson(file) {
  let dir = path.resolve(path.dirname(file));
  for (;;) {
    const p = path.join(dir, "package.json");
    if (fs.existsSync(p)) return p;
    const up = path.dirname(dir);
    if (up === dir) return null;
    dir = up;
  }
}

const problems = [];
let linksChecked = 0;
let commandsChecked = 0;
const report = (file, n, msg) => problems.push(`${file}:${n}: ${msg}`);

for (const file of files) {
  const { prose, code } = parse(file);
  for (const { n, text } of prose) {
    const noCode = text.replace(/`[^`]*`/g, "");
    const targets = [
      ...[...noCode.matchAll(/!?\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g)].map((m) => m[1]),
      ...[...noCode.matchAll(/^\s{0,3}\[[^\]]+\]:\s*<?(\S+?)>?(?:\s+.*)?$/g)].map((m) => m[1]),
      ...[...noCode.matchAll(/<(?:img|a)\s[^>]*(?:src|href)="([^"]+)"/g)].map((m) => m[1]),
    ];
    for (const t of targets) {
      if (/^[a-z][a-z0-9+.-]*:/i.test(t) || t.startsWith("//")) continue; // external, mailto:, etc.
      linksChecked++;
      const [rawPath, frag] = t.split("#");
      const decoded = decodeURIComponent(rawPath);
      const target = decoded === "" ? file : decoded.startsWith("/") ? path.normalize(decoded.slice(1)) : path.normalize(path.join(path.dirname(file), decoded));
      if (!fs.existsSync(target)) { report(file, n, `broken link: ${t} (${target} does not exist)`); continue; }
      if (frag !== undefined && /\.mdx?$/i.test(target) && !anchors(target).has(decodeURIComponent(frag).toLowerCase())) {
        report(file, n, `missing anchor: ${t} (no heading "#${frag}" in ${target})`);
      }
    }
  }
  const pkgPath = nearestPackageJson(file);
  const scripts = pkgPath ? Object.keys(JSON.parse(fs.readFileSync(pkgPath, "utf8")).scripts ?? {}) : null;
  const inlineCode = prose.flatMap(({ n, text }) => [...text.matchAll(/`([^`]+)`/g)].map((m) => ({ n, text: m[1] })));
  for (const { n, text } of [...code, ...inlineCode]) {
    for (const m of text.matchAll(/\b(npm|pnpm|yarn|bun)\s+run\s+([\w:.-]+)/g)) {
      commandsChecked++;
      if (!scripts) report(file, n, `"${m[0]}" but no package.json above ${file}`);
      else if (!scripts.includes(m[2])) report(file, n, `"${m[0]}": no "${m[2]}" script in ${path.relative(".", pkgPath)}`);
    }
  }
}

for (const p of problems) console.log(p);
console.log(`docs: ${files.length} files, ${linksChecked} local links, ${commandsChecked} script commands, ${problems.length} problems`);
if (problems.length) process.exitCode = 1;

// .markdownlint-cli2.jsonc at the repository root. Run: npx markdownlint-cli2
{
  "config": {
    "default": true,
    // Long lines are fine in prose; wrapping makes diffs noisy.
    "MD013": false,
    // Same heading text is fine under different parents (e.g. "Usage" per command).
    "MD024": { "siblings_only": true },
    // Allow the small amount of HTML GitHub renders well.
    "MD033": { "allowed_elements": ["details", "summary", "kbd", "br", "img", "a"] },
    // Fenced code blocks must say their language.
    "MD040": true,
    // Link fragments must match a heading in the same file.
    "MD051": true
  },
  "globs": ["**/*.md"],
  "ignores": ["node_modules/**", "**/node_modules/**", "CHANGELOG.md", "dist/**"]
}