Add a Go linter for the docs/ content contract (#4584)

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).


Claude-Session: https://claude.ai/code/session_013XDcHxZk9UzfzMLayG66Zq

Co-authored-by: Claude <noreply@anthropic.com>

Author: kyleconroy

docs/howto/ci-cd.md

@@ -38,7 +38,7 @@ database schema.  Learn more about uploading projects [here](push.md)
 
 ## General setup
 
-Install `sqlc` using the [suggested instructions](../overview/install).
+Install `sqlc` using the [suggested instructions](../overview/install.md).
 
 Create three steps in your pipeline for `sqlc diff`, `sqlc vet`, and `sqlc
 verify`. Run `sqlc push` after merge on your `main` branch.
@@ -98,9 +98,8 @@ jobs:
 
 ### push
 
-```{note}
-Pushing a project is powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
-```
+> [!NOTE]
+> Pushing a project is powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
 
 The following GitHub Workflow configuration runs [sqlc push](push.md) on
 every push to `main`. Create an auth token via the
@@ -125,9 +124,8 @@ jobs:
 
 ### verify
 
-```{note}
-Verify database migrations is powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
-```
+> [!NOTE]
+> Verify database migrations is powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
 
 ```yaml
 name: sqlc

docs/howto/embedding.md

@@ -1,4 +1,4 @@
-#### Embedding structs
+# Embedding structs
 
 Embedding allows you to reuse existing model structs in more queries, resulting
 in less manual serialization work. First, imagine we have the following schema

docs/howto/managed-databases.md

@@ -79,9 +79,9 @@ sql:
 
 With managed databases configured, `sqlc vet` will automatically create a hosted ephemeral database with your
 schema and use that database when running lint rules that require a
-database connection, e.g. any [rule relying on `EXPLAIN ...` output](vet.md#rules-using-explain-output).
+database connection, e.g. any [rule relying on `EXPLAIN ...` output](vet.md#rules-using-explain--output).
 
-If you don't yet have any vet rules, the [built-in sqlc/db-prepare rule](vet.md#sqlc-db-prepare)
+If you don't yet have any vet rules, the [built-in sqlc/db-prepare rule](vet.md#sqlcdb-prepare)
 is a good place to start. It prepares each of your queries against the database
 to ensure the query is valid. Here's a minimal working configuration:
 

docs/howto/named_parameters.md

@@ -46,9 +46,8 @@ type UpdateAuthorNameParams struct {
 If the `sqlc.arg()` syntax is too verbose for your taste, you can use the `@`
 operator as a shortcut.
 
-```{note}
-The `@` operator as a shortcut for `sqlc.arg()` is not supported in MySQL.
-```
+> [!NOTE]
+> The `@` operator as a shortcut for `sqlc.arg()` is not supported in MySQL.
 
 ```sql
 -- name: UpsertAuthorName :one

docs/howto/overrides.md

@@ -1,8 +1,7 @@
 # Overriding types
 
-:::{note}
-Type overrides and field renaming are only fully-supported for Go.
-:::
+> [!NOTE]
+> Type overrides and field renaming are only fully-supported for Go.
 
 In many cases it's useful to tell `sqlc` explicitly what Go type you want it to
 use for a query input or output. For instance, by default when you use
@@ -39,11 +38,10 @@ sql:
           go_type: "time.Time"
 ```
 
-:::{tip}
-  A single `db_type` override configuration applies to either nullable or non-nullable
-  columns, but not both. If you want the same Go type to override regardless of
-  nullability, you'll need to configure two overrides: one with `nullable: true` and one without.
-:::
+> [!TIP]
+> A single `db_type` override configuration applies to either nullable or non-nullable
+> columns, but not both. If you want the same Go type to override regardless of
+> nullability, you'll need to configure two overrides: one with `nullable: true` and one without.
 
 ## The `overrides` list
 
@@ -54,7 +52,7 @@ Each element in the `overrides` list has the following keys:
 - `column`:
   - A column name to override. The value should be of the form `table.column` but you can also specify `schema.table.column` or `catalog.schema.table.column`. `column` and `db_type` are mutually exclusive.
 - `go_type`:
-  - The fully-qualified name of a Go type to use in generated code. This is usually a string but can also be [a map](#the-go-type-map) for more complex configurations.
+  - The fully-qualified name of a Go type to use in generated code. This is usually a string but can also be [a map](#the-go_type-map) for more complex configurations.
 - `go_struct_tag`:
   - A reflect-style struct tag to use in generated code, e.g. `a:"b" x:"y,z"`.
     If you want `json` or `db` tags for all fields, configure `emit_json_tags` or `emit_db_tags` instead.
@@ -68,15 +66,13 @@ Each element in the `overrides` list has the following keys:
     Note that this only applies to `db_type` overrides and has no effect on `column` overrides.
     Defaults to `false`.
 
-:::{tip}
-  A single `db_type` override configuration applies to either nullable or non-nullable
-  columns, but not both. If you want the same Go type to override regardless of nullability, you'll
-  need to configure two overrides: one with `nullable: true` and one without.
-:::
+> [!TIP]
+> A single `db_type` override configuration applies to either nullable or non-nullable
+> columns, but not both. If you want the same Go type to override regardless of nullability, you'll
+> need to configure two overrides: one with `nullable: true` and one without.
 
-:::{note}
-When generating code, `column` override configurations take precedence over `db_type` configurations.
-:::
+> [!NOTE]
+> When generating code, `column` override configurations take precedence over `db_type` configurations.
 
 ### The `go_type` map
 

docs/howto/push.md

@@ -1,8 +1,7 @@
 # `push` - Uploading projects
 
-```{note}
-`push` is powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
-```
+> [!NOTE]
+> `push` is powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
 
 *Added in v1.24.0*
 

docs/howto/vet.md

@@ -4,7 +4,7 @@
 
 `sqlc vet` runs queries through a set of lint rules.
 
-Rules are defined in the `sqlc` [configuration](../reference/config) file. They
+Rules are defined in the `sqlc` [configuration](../reference/config.md) file. They
 consist of a name, message, and a [Common Expression Language
 (CEL)](https://github.com/google/cel-spec) expression. Expressions are evaluated
 using [cel-go](https://github.com/google/cel-go).  If an expression evaluates to
@@ -48,7 +48,7 @@ each CEL expression has access to the output from running `EXPLAIN ...` on your
 via the `postgresql.explain` and `mysql.explain` variables.
 This output is quite complex and depends on the structure of your query but sqlc attempts
 to parse and provide as much information as it can. See
-[Rules using `EXPLAIN ...` output](#rules-using-explain-output) for more information.
+[Rules using `EXPLAIN ...` output](#rules-using-explain--output) for more information.
 
 Here are a few example rules just using the basic configuration and query information available
 to the CEL expression environment. While these examples are simplistic, they give you a flavor

docs/reference/changelog.md

@@ -548,7 +548,7 @@ Like upload, `push` should be run when you tag a release of your application. We
 
 #### MySQL support in `createdb`
 
-The `createdb` command, added in the last release, now supports MySQL. If you have a cloud project configured, you can use `sqlc createdb` to spin up a new ephemeral database with your schema and print its connection string to standard output. This is useful for integrating with other tools. Read more in the [managed databases](../howto/managed-databases.md#with-other-tools) documentation.
+The `createdb` command, added in the last release, now supports MySQL. If you have a cloud project configured, you can use `sqlc createdb` to spin up a new ephemeral database with your schema and print its connection string to standard output. This is useful for integrating with other tools. Read more in the [managed databases](../howto/managed-databases.md) documentation.
 
 #### Plugin interface refactor
 
@@ -628,7 +628,7 @@ When you have a cloud project configured, you can use the new `sqlc createdb`
 command to spin up a new ephemeral database with your schema and print its
 connection string to standard output. This is useful for integrating with other
 tools. Read more in the [managed
-databases](../howto/managed-databases.md#with-other-tools) documentation.
+databases](../howto/managed-databases.md) documentation.
 
 #### Support for pgvector
 
@@ -833,7 +833,7 @@ full list.
 
 #### Plugin access to environment variables
 
-If you're authoring a [sqlc plugin](../guides/plugins.html), you can now configure
+If you're authoring a [sqlc plugin](../guides/plugins.md), you can now configure
 sqlc to pass your plugin the values of specific environment variables.
 
 For example, if your plugin
@@ -1254,7 +1254,7 @@ rules:
 database server. We'll expand this functionality over time, but for now it
 powers the `sqlc/db-prepare` built-in rule.
 
-When a [database](config.html#database) is configured, the
+When a [database](config.md#database) is configured, the
 `sqlc/db-preapre` rule will attempt to prepare each of your
 queries against the connected database and report any failures.
 

docs/reference/config.md

@@ -204,7 +204,7 @@ See [Overriding types](../howto/overrides.md) for an in-depth guide to using typ
 
 #### kotlin
 
-> Removed in v1.17.0 and replaced by the [sqlc-gen-kotlin](https://github.com/sqlc-dev/sqlc-gen-kotlin) plugin. Follow the [migration guide](../guides/migrating-to-sqlc-gen-kotlin) to switch.
+> Removed in v1.17.0 and replaced by the [sqlc-gen-kotlin](https://github.com/sqlc-dev/sqlc-gen-kotlin) plugin. Follow the [migration guide](../guides/migrating-to-sqlc-gen-kotlin.md) to switch.
 
 - `package`:
   - The package name to use for the generated code.
@@ -215,7 +215,7 @@ See [Overriding types](../howto/overrides.md) for an in-depth guide to using typ
 
 #### python
 
-> Removed in v1.17.0 and replaced by the [sqlc-gen-python](https://github.com/sqlc-dev/sqlc-gen-python) plugin. Follow the [migration guide](../guides/migrating-to-sqlc-gen-python) to switch.
+> Removed in v1.17.0 and replaced by the [sqlc-gen-python](https://github.com/sqlc-dev/sqlc-gen-python) plugin. Follow the [migration guide](../guides/migrating-to-sqlc-gen-python.md) to switch.
 
 - `package`:
   - The package name to use for the generated code.

docs/reference/macros.md

@@ -20,7 +20,7 @@ FROM authors
 WHERE lower(name) = ?;
 ```
 
-See more examples in [Naming parameters](../howto/named_parameters).
+See more examples in [Naming parameters](../howto/named_parameters.md).
 
 ## `sqlc.embed`
 
@@ -72,7 +72,7 @@ func (q *Queries) GetStudentAndScore(ctx context.Context, id int64) (GetStudentA
 }
 ```
 
-See a full example in [Embedding structs](../howto/embedding).
+See a full example in [Embedding structs](../howto/embedding.md).
 
 ## `sqlc.narg`
 
@@ -92,7 +92,7 @@ FROM authors
 WHERE LOWER(name) = ?;
 ```
 
-See more examples in [Naming parameters](../howto/named_parameters).
+See more examples in [Naming parameters](../howto/named_parameters.md).
 
 ## `sqlc.slice`