sbx: restructure governance docs and add API reference#25162
Conversation
Splits the existing security/governance and security/policy pages into a new governance section with concepts, local, organization, monitoring, and API reference sub-pages, and adds a custom api-reference Hugo layout that renders the colocated OpenAPI 3 spec directly from the spec file. The layout reads the spec via transform.Unmarshal, resolves $ref nodes through a small returning partial, and overrides baseof's main block to take the full content width. The built-in right-rail TOC is replaced with a sticky endpoint navigator that groups operations by tag with method-colored pills. Each operation card shows method/path, summary, description, parameters, request body, and responses. Responses use native <details> elements so the list of status codes stays scannable; 2xx defaults to open. JSON examples are wrapped in the site's syntax-light/dark utility so Chroma classes pick up the theme. Each operation also exposes a copy-as-cURL button that assembles a ready-to-paste command from the spec's path and query parameter examples, the bearer-auth scheme (with $TOKEN as a literal placeholder), and the request body's default JSON example. A companion api-reference.markdown.md template renders the same spec as a clean markdown document so the page's "Copy Markdown" / "View Markdown" actions and the .md alternate link return real content instead of just the page title. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
This PR restructures sandbox governance docs into a clean multi-page hierarchy and adds an OpenAPI-rendered API reference page. The redirect aliases on local.md and org.md correctly cover the old security/policy and security/governance URLs. Two issues found in the newly added content.
| See [Local policy](local.md). | ||
|
|
||
| **Organization policy** is configured centrally in the Docker Admin Console or | ||
| via the [Governance API](api.md). Rules defined at the org level apply |
There was a problem hiding this comment.
[MEDIUM] Links to api.md will fail — API reference lives at api/index.md (leaf bundle)
Multiple files in content/manuals/ai/sandboxes/governance/ link to api.md as a sibling file:
_index.md line 17: [Governance API](api.md)
_index.md line 38: [API reference](api.md)
org.md line 18: [Governance API](api.md)
org.md line 110: [API](api.md)
local.md line 158: [API](api.md)
concepts.md line 19: [Governance API](api.md)
No sibling api.md file exists — the API reference is a leaf bundle at governance/api/index.md. Hugo link checking will report these as broken links. Change the links to api/ (or api/index.md) to correctly point at the bundle's index page.
There was a problem hiding this comment.
I think the link resolves correctly it seems, but that's just luck. Agree that we should link to the actual file.
There was a problem hiding this comment.
You're right that Hugo is likely resolving it — Hugo's link resolver is forgiving and will often find the target even with imprecise paths. But as you noted, relying on that is fragile. Using api/ (or api/index.md) makes the intent explicit and ensures the link works predictably across different contexts (ref lookups, relrefs, etc.).
Thanks for confirming the fix makes sense!
| type: | ||
| type: string | ||
| description: > | ||
| Identifies the rule-set format. Currently always `allowlist_v0`, |
There was a problem hiding this comment.
[LOW] Time-relative language "Currently always allowlist_v0" violates style guide
Docker's style guide prohibits time-relative language like "currently" because it implies the state may change and becomes stale. Documentation should describe the product as it is today.
Suggested rewrite:
description: >
Identifies the rule-set format. Always `allowlist_v0`,
corresponding to the `allowlist_v0` property on the full Policy object.The same phrase appears at the same line in static/manuals/ai/sandboxes/governance/api.yaml.
There was a problem hiding this comment.
Thanks for confirming! I'll mark this as resolved once the upstream fix is merged.
2 participants
Summary
Splits the existing
security/governanceandsecurity/policypages into a new governance section with concepts, local, organization, monitoring, and API reference sub-pages, and adds a customapi-referenceHugo layout that renders the colocated OpenAPI 3 spec directly.The layout reads the spec with
transform.Unmarshal, resolves$refnodes through a tiny returning partial, overridesbaseof'smainblock to take the full content width, and adds a sticky right-rail endpoint navigator grouped by tag. Each operation card shows method/path, summary, description, parameters, request body, and responses; responses are native<details>with 2xx open by default; JSON examples use the site'ssyntax-light/syntax-darkutility for theming. Every operation also exposes a copy-as-cURL button that assembles a ready-to-paste command from spec parameter and request-body examples.A companion
api-reference.markdown.mdtemplate renders the same spec as a clean markdown document so the page's Copy/View Markdown actions and the.mdalternate return real content.Learnings
prettierconfig only applies theprettier-plugin-go-templateparser to*.html. Runningprettier --writeonlayouts/*.markdown.mdmangles Go template syntax (e.g.{{- /* ... */ -}}and*.yaml). Format the HTML layout, leave the markdown template alone.docker buildx bake validatestill fails inside a git worktree, but a plainhugo --renderToMemoryorhugo -d <out>does build the page — the only post-build error is the deferred Tailwind CSS transform (missingtailwindcssCLI), which doesn't gate template rendering.Generated by Claude Code