Add a Go linter for the docs/ content contract - #4584
Merged
Conversation
internal/docs validates the documentation source tree with goldmark and runs from go test, so doc-breaking changes fail CI without any JavaScript toolchain. It enforces the contract the external site consumer relies on: every page parses as GFM and starts with exactly one level-1 heading; relative links and images resolve to files inside docs/, with anchor fragments checked against GitHub-style heading slugs; every page appears exactly once in toc.yaml and every toc.yaml entry names a real page; no raw HTML other than comments; and no leftover MyST directives. Fix everything the linter found in the existing docs: convert the eight remaining MyST admonitions to GitHub alert syntax, add the missing level-1 heading to the embedding guide, point extensionless and .html links (which only resolved under Sphinx) at the actual .md files, and correct anchors that did not match GitHub slugging (#sqlcdb-prepare, #rules-using-explain--output, #the-go_type-map, and stale #with-other-tools fragments in the changelog). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013XDcHxZk9UzfzMLayG66Zq
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.
Follow-up to #4583:
docs/is now validated in CI using Go and only Go.The linter
internal/docsparses every page with goldmark (pure Go, CommonMark + GFM — the same parser Hugo uses) and enforces the contract an external site consumer relies on:docs/; anchor fragments (config.md#database) are checked against GitHub-style heading slugs, including duplicate-heading-1suffixestoc.yaml(section orunlisted), and everytoc.yamlentry names a real file:::{note}paragraphs and```{note}fences are rejected with a pointer to GitHub alert syntaxIt runs as
TestDocsunder plaingo test ./..., reporting violations asfile: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:
:::{note}/```{note}(overrides, ci-cd, push, named_parameters) — converted to> [!NOTE]/> [!TIP]../howto/named_parameters) and.html(../guides/plugins.html) targets — now point at the actual.mdfiles#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-toolsfragments in the changelog now link to the page itself####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