feat(docsite): require src= on Go code blocks of module READMEs (quick-261118-qsd)

This commit is contained in:
Jakub Zych
2026-11-18 20:18:38 +01:00
parent 1e56d750ef
commit 8c03cc3621
11 changed files with 43 additions and 40 deletions

View File

@@ -45,6 +45,6 @@ summer docs:sync
summer docs:serve
```
`summer help docs:build` and `summer help docs:sync` show examples. `docs:build` fails, and writes nothing, when a page names an identifier that does not exist, links to a missing page or anchor, shows a command that neither `summer` nor an application binary has, or has a `src=` code block that differs from its source. It also fails on a Go code block (including `golang`) without a `src=` reference and on a `src=` code block inside a callout, blockquote or list item; `src=` works on top-level code blocks of docs pages and module READMEs. A `src=` target must be code `go test ./...` compiles and runs, that is a file in the default build, inside a `Test` function or an `Example` with an `// Output:` comment, or a function one of them calls. After you change code that a page shows, run `summer docs:sync` to refresh the copies.
`summer help docs:build` and `summer help docs:sync` show examples. `docs:build` fails, and writes nothing, when a page names an identifier that does not exist, links to a missing page or anchor, shows a command that neither `summer` nor an application binary has, or has a `src=` code block that differs from its source. It also fails on a Go code block (including `golang`) without a `src=` reference, in docs pages and module READMEs alike, and on a `src=` code block inside a callout, blockquote or list item; `src=` works on top-level code blocks of docs pages and module READMEs. A `src=` target must be code `go test ./...` compiles and runs, that is a file in the default build, inside a `Test` function or an `Example` with an `// Output:` comment, or a function one of them calls. After you change code that a page shows, run `summer docs:sync` to refresh the copies.
`docs:serve` listens only on a loopback address unless you pass `--allow-remote`. Use it to preview search, which browsers block when you open the built files directly from disk.