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:
@@ -243,7 +243,8 @@ func TestPhase11_1Acceptance(t *testing.T) {
|
||||
}
|
||||
}
|
||||
// The acceptance scanner is independent of docsite: a src= fence
|
||||
// inside a blockquote or list is nested, and a module README has none.
|
||||
// inside a blockquote or list is nested, in a docs/ page and a
|
||||
// module README alike.
|
||||
err := filepath.WalkDir(filepath.Join(repoRoot, "docs"), func(p string, d fs.DirEntry, err error) error {
|
||||
if err != nil {
|
||||
return err
|
||||
@@ -274,8 +275,8 @@ func TestPhase11_1Acceptance(t *testing.T) {
|
||||
}
|
||||
rel, _ := filepath.Rel(repoRoot, p)
|
||||
for _, f := range scanDocFences(filepath.ToSlash(rel), readFile(t, p)) {
|
||||
if f.src != "" {
|
||||
t.Errorf("%s:%d: module README has a src= fence", f.file, f.line)
|
||||
if f.src != "" && f.nested {
|
||||
t.Errorf("%s:%d: src= fence is nested (%s)", f.file, f.line, f.src)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
@@ -283,10 +284,9 @@ func TestPhase11_1Acceptance(t *testing.T) {
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
// Every page, module README API pages included, captions exactly
|
||||
// its top-level src= fences.
|
||||
for _, p := range pages {
|
||||
if p.Module != "" {
|
||||
continue
|
||||
}
|
||||
n := 0
|
||||
for _, f := range pageFences(t, p.Source) {
|
||||
if f.src != "" && !f.nested {
|
||||
@@ -298,15 +298,6 @@ func TestPhase11_1Acceptance(t *testing.T) {
|
||||
t.Errorf("%s has %d figcaptions, want %d top-level src= fences", p.URL, got, n)
|
||||
}
|
||||
}
|
||||
api, err := filepath.Glob(filepath.Join(out, "api", "*.html"))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, p := range api {
|
||||
if strings.Contains(readFile(t, p), "<figcaption>") {
|
||||
t.Errorf("%s has a figcaption", p)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
// SC5: the concept map and the acme/blog walkthrough exist, and the
|
||||
|
||||
@@ -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>`.
|
||||
|
||||
Reference in New Issue
Block a user