A Web Device site is not one large page configuration. It keeps three different responsibilities separate: page declarations in pages/, reader-facing content objects in content/, and site configuration, components, and visual system in .web/.
| Location | Owns | Does not own |
|---|---|---|
pages/ | Page entry points, layouts, page SEO, and presentation rules for lists or details | Article or product body copy |
content/ | Identified content objects and their body, front matter, tags, and relationships | Site-wide component implementation |
.web/ | Site configuration, site components, tokens, themes, and template assets | The body of every content item |
.route/ | Declaring the blocklet's Web entry to a local or published runtime | Page implementation or content data |
A minimal directory can look like this:
my-site/
├── .route/
│ └── web
├── .web/
│ ├── site.yaml
│ └── components/
│ └── site-home/
├── pages/
│ └── index/
│ └── layout.aup
└── content/
└── articles/
└── first-post/
└── content.mdChoose the directory by responsibility
Use this order to decide where a file belongs:
- Does it define the presentation of a site URL? Put it in
pages/<name>/. - Is it an identified object with a title, slug, body, or relationships that lists and detail pages will consume? Put it in
content/<type>/<slug>/. - Does it affect components, configuration, templates, or visual behavior across pages? Put it in
.web/. - Does it only hand the current directory to the Web runtime? Put it in
.route/, not in a layout or content item.
The practical result is that one content object can be used by several pages or components without duplicating its body into a layout, and one component can serve several pages without making every object carry UI.
Pages and content are not the same thing
pages/index/ normally supplies the home-page entry point. An ordinary pages/about/ directory supplies the /about/ page entry point. The runtime also discovers collection types from content/<type>/, so a content collection can supply list and detail routes; that does not turn every content directory into a hand-authored page.
The page structure under pages/ and the object structure under content/ can evolve independently. For example, articles can remain under content/articles/ while the site later gains a different home-page or list layout. Do not move original content just to change how it is displayed.
.web/ is the site layer, not a second content store
The current runtime treats .web/site.yaml as the single-file form of site-level configuration. Locale, locales, render mode, color scheme, comment switches, plus SEO, template, and theme settings each have an explicit site-layer home. tokens.json, redirects, and template/logo.svg remain independent files because they represent design tokens, line-oriented redirect rules, and an asset respectively.
Site components live in .web/components/. A page AUP layout composes those components. The runtime also has a separate static-tree path for supported native AUP nodes; that does not make arbitrary native nodes valid page-layout sections. Components remain the site layer for reusable Web HTML, styling, and interaction. See Build a page with AUP.
Read next
- To make a page render, continue with Build a page with AUP.
- To create article, documentation, or product objects for pages to consume, continue with Content objects, metadata, and locales.
- To check paths, locale prefixes, and reserved routes, continue with Routes, navigation, and locales.
This page describes the directory-reading boundary in ARC 2.0.0-beta.25. Older Cookbook material or historical sites can use compatibility layouts; run the local checks before using an older convention as a new-site template.