docs(breakwater): compile README Go examples via src= (quick-261118-qsd)

- the Usage fence becomes two src= references to ExampleRender and
  ExamplePurify, filled by summer docs:sync
- the Phase 11.1 SC4 acceptance scan now allows top-level src= fences
  in module READMEs (nested ones are still refused) and expects the
  api/<name> pages to caption them like docs/ pages
This commit is contained in:
Jakub Zych
2026-11-18 19:30:29 +01:00
parent 721830c502
commit 48527e4206
2 changed files with 19 additions and 18 deletions

View File

@@ -25,12 +25,22 @@ The policy is the PHP `golem15/forum` HTMLPurifier config 1:1 (decision note `.p
## Usage
```go
```go src=modules/breakwater/example_test.go#ExampleRender
// A forum post: store the rendered HTML on write and serve it as is.
html := breakwater.Render(post.Content)
post := "See [the docs](https://example.com/docs) and <b onclick=\"x()\">this</b>.\n\n<script>alert(1)</script>"
html := breakwater.Render(post)
fmt.Println(html)
// Output:
// <p>See <a href="https://example.com/docs" rel="nofollow noopener" target="_blank">the docs</a> and this.</p>
```
```go src=modules/breakwater/example_test.go#ExamplePurify
// Content stored as HTML: the same allow-list, no Markdown pass.
clean := breakwater.Purify(training.ContentHTML)
stored := `<p onclick="x()">Hi <b>there</b><img src="a.jpg"></p><a href="tel:+48">call</a>`
clean := breakwater.Purify(stored)
fmt.Println(clean)
// Output:
// <p>Hi <b>there</b></p>call
```
`breakwater.Render("See [the docs](https://example.com/docs) and <b onclick=\"x()\">this</b>.")` gives `<p>See <a href="https://example.com/docs" rel="nofollow noopener" target="_blank">the docs</a> and this.</p>`.