メインコンテンツへスキップ

ARC 2.0.0-beta.25

Content objects, metadata, and locales

Keep each item as a directory-shaped object and manage body and metadata with an explicit read order.

Web Device treats an article, document, product, or event as a directory-shaped object, not as a database row that must be moved elsewhere. The object directory is the source of truth; pages and lists read a normalized view from it.

text
content/
└── articles/
    └── first-post/
        ├── content.md
        ├── content.zh.md
        ├── tags/
        │   └── AFS
        ├── related/
        │   └── docs--web-device-overview
        └── cover.png

Here, articles is the content type and first-post is the object directory. The directory name contributes the default slug, but an author can explicitly provide title, summary, date, author, tags, or related objects in front matter.

Body and locale variants

The current reader accepts content.md and index.md. When both exist, content.md wins. For a requested locale, it first looks for content.<locale>.md or index.<locale>.md, then falls back to the default-language file. content.zh.md is therefore the normal home for a Chinese body, not a separate object directory.

Do not simply copy the default body and change a title. A locale file should be what a reader actually receives; only when it is absent does the runtime use the default file. Page layouts and SEO can have their own locale variants too; see Routes, navigation, and locales.

Metadata read order

The same field can come from three locations. The current read order is:

  1. Markdown front matter.
  2. Directory-field files in the object directory.
  3. meta in compatible .aup/default.json input.

An earlier source overrides a later source. New Markdown content therefore does not need to duplicate old JSON metadata, but a compatibility consumer must not have its JSON removed without its own check.

Filenames in tags/ form the tag list. Entries in related/ use type--slug as their filename, for example docs--web-device-overview; file content can provide a fallback title. A cover image is an object asset, not part of the body.

Keep objects movable and re-organizable

An object should say what it is, not which slot it currently occupies on the home page. Keep home-page ordering, filters, and component selection in the page source/binding and layout. The same object can then appear in an article list, a topic page, related reading, or a future UI without rewriting or moving the original file.

Objects can also use grouped directories, but grouping and version layers affect detail paths and collection discovery. Start a new collection with the flat content/<type>/<slug>/ shape; add nesting only when a specific route requirement calls for it.

Accept one content object

  1. Write content.md, with front matter for at least a title and any required summary/date.
  2. If Chinese is needed, add content.zh.md; do not duplicate the slug directory.
  3. Put optional tags, related items, and a cover inside the object directory.
  4. Run the site's arc dsl validate ., arc blocklet check ., and build.
  5. Open the detail and list pages in each declared locale and confirm that body, title, and links come from the intended object variant.

To restrict who can read an object, set collections.<type>.access and tighten individual records with front-matter access. See Restrict who can read a page.

For querying these objects from a page, see Bind content to a page. For exact field and compatibility-input boundaries, see Source-binding reference.

For a source-and-rendered-result example inside a Markdown body, see Embed YouTube and X in Markdown.