跳到主要内容

ARC 2.0.0-beta.25

内容对象、元数据与语言

把一篇内容保留为目录化对象,并用明确的读取优先级管理正文和元数据。

Web Device 把一篇文章、文档、产品或事件当作一个目录化对象,而不是数据库里一行必须迁移出去的数据。对象目录是事实源;页面和列表从中读取一个规范化视图。

text
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.mdindex.md。若两者同时存在,content.md 优先。对于指定语言,先找 content.<locale>.mdindex.<locale>.md,再回退到默认语言文件;因此 content.zh.md 是中文正文的正常位置,而不是另开一套对象目录。

不要只复制默认正文再改标题。locale 文件应当是读者真正会读到的版本;若没有该语言版本,运行时才使用默认文件。页面级 layout 和 SEO 也可以有自己的 locale 变体,详见路由、导航与语言

元数据的读取优先级

同一字段可以来自三个位置。当前读取顺序是:

  1. Markdown front matter;
  2. 对象目录中的目录字段文件;
  3. 兼容的 .aup/default.json 中的 meta

前面的来源覆盖后面的来源。也就是说,新的 Markdown 内容不必重复维护旧 JSON 元数据;但尚在使用 JSON 的兼容消费者也不能未经检查就删除。

tags/ 目录的文件名形成标签列表。related/ 中使用 type--slug 作为文件名,例如 docs--web-device-overview;文件内容可作为备用标题。cover 图片是对象资产而不是正文的一部分。

保持对象可移动、可重新组织

内容对象应描述“它是什么”,而不是“它在当前首页的第几块”。把首页排序、过滤或组件选择留给页面 source/binding 和 layout。这样同一对象可以同时出现于文章列表、专题页、相关推荐或未来的其他 UI,而无需改写或搬动原始文件。

对象也可以使用分组目录;不过分组和版本层级会影响详情路径及集合推导。第一次建立内容集合时,先使用扁平的 content/<type>/<slug>/ 结构,等具体路由需求出现后再引入嵌套层级。

验收一条内容对象

  1. content.md,用 front matter 声明至少标题和必要的摘要/日期。
  2. 如需要中文,新增 content.zh.md,不要复制出第二个 slug 目录。
  3. 把可选标签、相关项和封面放在对象目录内。
  4. 运行站点的 arc dsl validate .arc blocklet check . 与构建。
  5. 在每个已声明 locale 中打开详情页和列表页,确认正文、标题和链接来自正确的对象版本。

要限制谁能读一个对象,写 collections.<type>.access,再用 front matter access 收紧单条记录。见限制谁能读一页

页面怎样查询这些对象,见把内容绑定到页面;字段和兼容输入的精确边界见来源绑定参考

Markdown 正文中把 source 与渲染结果放在一起的例子,见在 Markdown 中嵌入 YouTube 与 X