Skip to main content

ARC 2.0.0-beta.25

Routes, navigation, and locales

Derive paths from declared pages and content, and treat locale as a view of one site rather than a copied site.

Web Device paths begin with declared site structure, not strings scattered through components. pages/ contributes named pages, content/<type>/ contributes collections and detail objects, and a multi-locale site renders those paths in a locale view.

The basic path model

The current runtime uses these foundational rules:

DeclarationTypical serviceable path
pages/index/The home page /
pages/about/A named page /about/
content/articles/first-post/Collection and detail paths such as articles/first-post/
A tagged content collectionarticles/tags/<tag>/ and its paginated form
A collection with archive enabledYear and month archive paths

Build and multi-locale preview put the site paths into a locale context. A site with en and zh, for example, can render /en/about/ and /zh/about/. Do not create another en/ or zh/ directory beneath every content object to express a translation of the same item.

Declare locales

The default locale and available locales belong in .web/site.yaml:

yaml
locale: en
locales:
  - en
  - zh

When locales is absent, the current runtime can also derive a locale set from filenames under .aup/locales/*.json. That fallback suits an existing compatible app; a new site should explicitly state the languages it supports in site.yaml, so authors, builds, and reviewers operate against the same boundary.

Content bodies use locale files such as content.zh.md; page layouts use files such as layout.zh.aup; page SEO uses files such as seo/title.zh and seo/description.zh. Each overrides the default version in the same directory. Do not duplicate the whole site tree.

The boundary between navigation and URLs

Navigation describes how readers discover pages. Routing describes whether the runtime can serve a URL. They often relate, but neither replaces the other:

  • Adding a navigation link does not create a page or content object. First ensure the target path has a real page or content declaration.
  • A page directory does not automatically mean it belongs in every navigation menu. Treat public information architecture as an explicit navigation decision.
  • Hard-coding /zh/, /en/, or a content slug inside a component makes new locales, renames, and local preview more fragile. Prefer the current page locale and an already resolved object route.

Watch reserved names and collection collisions

Web Device has declared built-in and collection route shapes. search is a built-in search path; tags, page, and feed.xml carry dedicated semantics inside a collection. Once archive, pagination, or tag pages are enabled, some paths that could otherwise be slugs are shadowed by route rules.

Choose collection type names and common slugs before creating a collection. After enabling archive, feed, or pagination, rebuild and run link checks. A directory being creatable does not mean every URL derived from it is collision-free.

Local acceptance

  1. Put the default locale and explicit locale list in .web/site.yaml.
  2. Add one default content body and one content.<locale>.md body.
  3. Give at least one page a locale title/description, and add a layout variant only when necessary.
  4. Run arc blocklet build .; inspect generated pages and the sitemap for each language.
  5. With the blocklet running directly locally, open each language page, one detail page, and one navigation link.

For content-variant reading, see Content objects, metadata, and locales. For site configuration fields, see Site-wide configuration.