GeezerVison

Follow-up to #4583: docs/ is now validated in CI using Go and only Go.

The linter

internal/docs parses every page with goldmark (pure Go, CommonMark + GFM — the same parser Hugo uses) and enforces the contract an external site consumer relies on:

• every page parses as GFM and starts with exactly one level-1 heading (the page title)
• relative links and images resolve to files inside docs/; anchor fragments (config.md#database) are checked against GitHub-style heading slugs, including duplicate-heading -1 suffixes
• every page appears exactly once in toc.yaml (section or unlisted), and every toc.yaml entry names a real file
• no raw HTML or JSX, except HTML comments (git-cliff emits one in the changelog)
• no MyST/Sphinx leftovers: :::{note} paragraphs and ```{note} fences are rejected with a pointer to GitHub alert syntax

It runs as TestDocs under plain go test ./..., reporting violations as file:line: message. A second test, TestLintViolations, pins the linter's own behavior against a synthetic tree that breaks each rule once. These are unit tests rather than endtoend cases because the contract is a property of the documentation tree, not of anything the sqlc CLI does.

What the linter caught

Running it against the existing docs found 24 real issues, all fixed here:

• 8 MyST admonitions still using :::{note} / ```{note} (overrides, ci-cd, push, named_parameters) — converted to > [!NOTE] / > [!TIP]
• 9 links that only resolved under Sphinx: extensionless (../howto/named_parameters) and .html (../guides/plugins.html) targets — now point at the actual .md files
• 6 anchors that don't match GitHub slugging: #sqlc-db-prepare → #sqlcdb-prepare (slashes are dropped), #rules-using-explain-output → #rules-using-explain--output, #the-go-type-map → #the-go_type-map, and two stale #with-other-tools fragments in the changelog now link to the page itself
• 1 missing title: the embedding guide started with an #### heading instead of #

Dependencies

Adds github.com/yuin/goldmark (no transitive dependencies).

🤖 Generated with Claude Code

https://claude.ai/code/session_013XDcHxZk9UzfzMLayG66Zq

Generated by Claude Code