docs: comprehensive documentation audit and enhancement#19
Merged
Conversation
Closes 20 of 22 documentation-audit items, restructuring the docs around the Diátaxis framework and adding the standard open-source community and project-health files. Content & structure (Diátaxis): - Add Explanation quadrant: 15 site/explanation/*.md analyzer concept pages - Add How-to quadrant: 5 task-oriented guides (bare repo, monorepo, CI, MCP client, reading a burndown chart) - Add Reference glossary (site/glossary.md) - Add Release notes section (index + unreleased) wired into nav - Migrate page titles to sentence case across the site Community & project health: - CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, GOVERNANCE.md, THIRD_PARTY_NOTICES.md - GitHub issue templates + pull request template - README Maintainers / Contributing / License / Security / Support sections Architecture decisions: - ADRs (MADR): record-architecture-decisions, two-binary-split, libgit2-via-cgo; exposed in nav via site/adr -> ../docs/adr symlink Changelog: - Keep a Changelog 1.1.0 proposal as CHANGELOG.md.proposed.md (original CHANGELOG.md intentionally left untouched) - Thin site/contributing/changelog.md to a pointer AI-agent discoverability: - llms.txt and llms-full.txt Docs CI & linting: - .github/workflows/docs.yml jobs plus markdownlint, Vale, cspell, and lychee link-check configs mkdocs build --strict passes; no Go source touched. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The doc-quality jobs globbed **/*.md, sweeping in non-documentation markdown (.agents/**, .claude/**, specs/**, AGENTS.md) that produced 984 markdownlint errors and link/spell failures unrelated to the docs. Scope all doc-quality gates to the documentation surface (site/, docs/, and the root health files) — matching Vale's existing scope: - markdownlint, cspell, lychee globs narrowed to the doc surface Fix real issues within the documentation: - markdownlint: add a language to 36 bare code fences (MD040); add blank lines around the AI-agent scenario lists in README (MD032); auto-fix list-marker spacing, list/strong style (MD030/MD004/MD050) - MD025: disable front-matter-title detection — MkDocs Material pages intentionally carry both a YAML `title:` and a rendered `# H1` - cspell: seed technical terms, tool names, and proper nouns into the dictionary; normalize British spellings to US English (behaviour, licence, prioritise, weaponised, analysers) per the Google/Microsoft style packs (the intentional UK "licence" reference in sentiment.md is preserved via the dictionary) Make the advisory checks reliably green: - Vale/cspell get step-level continue-on-error. Job-level continue-on-error only unblocks the run; the check still reports failure. Step-level lets the job pass while annotations stay visible — matching the documented "advisory, non-blocking" intent. (Vale exits non-zero on any error-level finding regardless of fail_on_error.) Verified locally: markdownlint 0 errors, lychee 0 errors, cspell 0 issues, mkdocs build --strict exit 0. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Current lychee (lychee-action@v2) rejects --exclude-mail with "unexpected argument" (exit 2), which was the actual cause of the red link-check job — not broken links. mailto:/tel: links are excluded by default now and are also covered by .lycheeignore, so the flag is just dropped. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes 20 of 22 items from the documentation-audit plan, restructuring the docs around the Diátaxis framework and adding the standard open-source community and project-health files.
mkdocs build --strictpasses; no Go source is touched in this PR.What changed
Content & structure (Diátaxis)
site/explanation/*.mdanalyzer concept pagessite/glossary.mdCommunity & project health
CONTRIBUTING.md,CODE_OF_CONDUCT.md,SECURITY.md,SUPPORT.md,GOVERNANCE.md,THIRD_PARTY_NOTICES.mdArchitecture decisions (MADR)
site/adr → ../docs/adrsymlink (keepsdocs_dir: sitestrict-clean)Changelog
CHANGELOG.md.proposed.md— the originalCHANGELOG.mdis intentionally left untouched for the maintainer to applysite/contributing/changelog.mdthinned to a pointerAI-agent discoverability
llms.txtandllms-full.txtDocs CI & linting
.github/workflows/docs.ymljobs plus markdownlint, Vale, cspell, and lychee link-check configsNot included
doc.gopackage comments,example_*_test.go) — Go-source work that needs a separate implementation PRCHANGELOG.md.proposed.mdoverCHANGELOG.mdis left as a deliberate maintainer action.claude/,.agents/skills/,AGENTS.md,scripts/) are excluded from this docs PRVerification
mkdocs build --strict— exit 0🤖 Generated with Claude Code