Skip to content

Docs quality gates in CI: link check, spelling and style #66

Closed

Description

@dataGriff

Why

mkdocs build --strict catches broken internal links and nothing else. External links rot, typos slip in, and with a course landing in docs/learn/ the volume of prose is about to triple.

What

  • lychee for external links on PRs touching docs/** or README.md (cache, exclude localhost and the demo URLs, fail on 404/410, warn on timeouts).
  • codespell over docs/, README.md, AGENTS.md, CONTRIBUTING.md, SECURITY.md and Go comments, with an ignore list for identifiers (apic, httpbin, gjson, sigv4, …).
  • Vale with the write-good or Google style base and a small project vocabulary (docs/.vale/), tuned so the existing pages pass; British spelling, since the project already writes "licence" and "colour".
  • task docs:check runs all three locally; docs.yml runs them before the build.

Where

.github/workflows/docs.yml, Taskfile.yml, .lychee.toml, .codespellrc, .vale.ini, docs/.vale/, CONTRIBUTING.md.

Tests

The workflow itself; a deliberate typo in a PR must fail.

Activity

  1. dataGriff commented on Sep 24, 2026

    @dataGriff
    OwnerAuthor

    Done in #116 (commits ea2f929 and 3a77671).

    • codespell runs over the whole tree, in CI's lint job and in the docs workflow.
    • Vale fails on three kinds of error: British spelling outside code spans, project names in the wrong case, and repeated words. write-good's advice is available with --minAlertLevel=warning.
    • lychee checks external links on PRs and fails on 404 and 410. It caught a real one on its first run: Sigstore's old cosign install page.
    • Where they run: docs.yml runs all three in a check job before the build; task docs:check runs them locally.
    • Tested: planted mistakes fail each tool.

    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions