A page layout determines how one Web route assembles presentation, not where an article, product, or document body lives. Start with the route and reader task; then use components for repeated presentation and sources for content selection.
Choose the layout level
| Need | Place it in |
|---|---|
| A page’s default presentation | pages/<name>/layout.aup |
| A layout that truly differs by locale | pages/<name>/layout.<locale>.aup |
| A content object’s exceptional presentation | content/<type>/<slug>/layout.aup |
| One named presentation shared by several content objects | layouts/<name>.aup, selected by layout: <name> in front matter |
| Shared card/header/section presentation | .web/components/<name>/ |
| The body and identity of a reader-facing object | content/<type>/<slug>/content.md |
The current lookup prefers locale AUP, default AUP, locale JSON, default JSON, then a convention/default layout. That makes an AUP layout the normal source-first choice for a new page; JSON remains a compatibility form, not a reason to duplicate both by default.
Compose in the right direction
- Declare the page or collection route first.
- Declare any content source in the matching page/collection scope.
- Use a complete
$source.<name>value only where the layout/component contract expects it. - Compose a reusable Web component with explicit props rather than copying a repeated tree into every page.
- Keep a one-off detail layout next to the object only when the object really needs a different reader task.
Web Device page layouts use a Web-component-and-props model. A supported AUP tree can also be statically rendered through the Web renderer, but that does not make arbitrary native primitives valid as layout sections. Use components for reusable site presentation and use the direct-tree path only where the target’s support has been verified.
A content object chooses either an item-local layout.aup or one named layout through layout: <name>. Do not declare both. A named layout can attach a verified widget to content it renders; Markdown slides shows the complete content-plus-widget pattern.
Run layout validation and inspect the resulting route in the browser. A syntactically valid layout can still have an empty source, a wrong locale variant, or an unreadable narrow-width hierarchy.
For layout mechanics, see Build a page with AUP; for components, see Use and override components.