Web Device 把一篇文章、文档、产品或事件当作一个目录化对象,而不是数据库里一行必须迁移出去的数据。对象目录是事实源;页面和列表从中读取一个规范化视图。
content/
└── articles/
└── first-post/
├── content.md
├── content.zh.md
├── tags/
│ └── AFS
├── related/
│ └── docs--web-device-overview
└── cover.png这里 articles 是内容类型,first-post 是对象目录。目录名会参与默认 slug,但作者仍可在 front matter 中显式给出标题、摘要、日期、作者、标签或相关对象。
正文与语言版本
当前 reader 接受 content.md 和 index.md。若两者同时存在,content.md 优先。对于指定语言,先找 content.<locale>.md 或 index.<locale>.md,再回退到默认语言文件;因此 content.zh.md 是中文正文的正常位置,而不是另开一套对象目录。
不要只复制默认正文再改标题。locale 文件应当是读者真正会读到的版本;若没有该语言版本,运行时才使用默认文件。页面级 layout 和 SEO 也可以有自己的 locale 变体,详见路由、导航与语言。
元数据的读取优先级
同一字段可以来自三个位置。当前读取顺序是:
- Markdown front matter;
- 对象目录中的目录字段文件;
- 兼容的
.aup/default.json中的meta。
前面的来源覆盖后面的来源。也就是说,新的 Markdown 内容不必重复维护旧 JSON 元数据;但尚在使用 JSON 的兼容消费者也不能未经检查就删除。
tags/ 目录的文件名形成标签列表。related/ 中使用 type--slug 作为文件名,例如 docs--web-device-overview;文件内容可作为备用标题。cover 图片是对象资产而不是正文的一部分。
保持对象可移动、可重新组织
内容对象应描述“它是什么”,而不是“它在当前首页的第几块”。把首页排序、过滤或组件选择留给页面 source/binding 和 layout。这样同一对象可以同时出现于文章列表、专题页、相关推荐或未来的其他 UI,而无需改写或搬动原始文件。
对象也可以使用分组目录;不过分组和版本层级会影响详情路径及集合推导。第一次建立内容集合时,先使用扁平的 content/<type>/<slug>/ 结构,等具体路由需求出现后再引入嵌套层级。
验收一条内容对象
- 写
content.md,用 front matter 声明至少标题和必要的摘要/日期。 - 如需要中文,新增
content.zh.md,不要复制出第二个 slug 目录。 - 把可选标签、相关项和封面放在对象目录内。
- 运行站点的
arc dsl validate .、arc blocklet check .与构建。 - 在每个已声明 locale 中打开详情页和列表页,确认正文、标题和链接来自正确的对象版本。
要限制谁能读一个对象,写 collections.<type>.access,再用 front matter access 收紧单条记录。见限制谁能读一页。
页面怎样查询这些对象,见把内容绑定到页面;字段和兼容输入的精确边界见来源绑定参考。
Markdown 正文中把 source 与渲染结果放在一起的例子,见在 Markdown 中嵌入 YouTube 与 X。