Task: a documentation board: left nav, prose body, breadcrumb, previous/next, optional in-page TOC. This recipe only points at surface and component unit pages.
Outcome
- A docs board (or collection) served through the docs page surface
- Board
_nav.yaml(or equivalent nav tree) drives the left rail - One doc object renders as prose with working prev/next when the tree has neighbors
Steps (link out only)
- Have a working Web Device site: Recipe: first site.
- Understand content objects under
content/docs/: Content objects, metadata, and locales. - Board navigation conventions: Routes, navigation, and locales · Routes and locales reference.
- Mount the documentation shell — read the surface unit for author entry and props:
docs-pagesurface.
Canonical units for a docs board
| Role | Unit page |
|---|---|
| Board shell (nav + prose + chrome) | docs-page |
| In-page TOC (when enabled) | in-page-toc |
| Search entry (if the board exposes search) | search-page |
| List/pagination helpers (indexes) | pagination surface |
| Optional comments attachment | comments-surface surface — different layer from the AUP widget comments-surface |
Prose and structure inside a doc
Doc bodies are Markdown. Use unit pages for structure and directives; do not treat layout components as MD:
- Structure: heading · paragraph · fenced code · list · thematicBreak
- Directives:
::::steps·:::step·::embed· cards under Markdown hub - Portable AUP in document target (tabs etc.):
view·input— sample contract: Live examples: scope and contract
Layer discipline
| Need | Layer | Where the unit lives |
|---|---|---|
| Docs chrome / left nav | Web Device surface | /docs/web-device/surfaces/docs-page/ |
| Card list on a landing | Web Device layout component | /docs/web-device/components/... |
| Portable tree node | AUP primitive | /docs/aup/primitives/... |
| Web-only AUP chrome widget | AUP widget | /docs/aup/widgets/... |
Do not document multiple surfaces or components on this recipe page.
Related
- Collection list page when the board needs a non-docs collection landing
- Showcase mapping for AUP interactive demos (not the docs surface)