Frontmatter

什么是 frontmatter#

Frontmatter 是 markdown 文件最顶部、两行 --- 之间的一段 YAML，告诉 moss 这个页面的标题、日期、可见性等信息。

---
title: 我的第一篇文章
date: 2024-06-15
description: 搜索引擎和列表预览用的简短摘要。
---

下面是正文内容。

Frontmatter 不是必须的。没有 frontmatter 的文件照样会变成页面——moss 会用文件名作为标题。

固定字段表#

Frontmatter 使用固定字段表——moss 只识别本页列出的字段，其他自定义字段会被静默忽略。如果需要存储自定义的页面元数据，请写在正文中：一段 markdown 段落、::: {.meta} 围栏分区或数据表格。

description: 用于 SEO meta 标签、Open Graph 预览和 sitemap 摘要，不会渲染为页面上可见的导语。若需要可见的副标题或引言，请在 # H1 正下方加一段 > 引用块——默认主题会将 h1 + blockquote 样式化为导语。

标识#

描述页面本身的字段。

title: 是页面标题。在文章页面上，moss 始终将其渲染为正文上方的 <h1 class="moss-article-title">——若 title: 缺省则使用文件名（首字母大写）。如果正文本身以 # 同名标题 开头，该正文 H1 会被自动去重，读者只看到一个标题，而非两个。

正文中其他位置的 # H1 是章节标题，而非文档标题。moss 不会从正文结构推断标题——请在 title: 中写明，或依赖文件名。

如需在某篇文章上单独关闭注入的标题（例如某个特殊设计的着陆页），可写 title: ""（显式空字符串）。这与省略 title: 不同——省略会回退到文件名。文件夹与索引页面从不注入；它们的正文按作者所写渲染。

导航#

控制页面在网站导航和界面元素中的呈现。

可见性#

参见结构中对可见性的定义。

子页面#

这些字段控制文件夹页面如何展示其子页面。

children_source 的值是一个 wikilink，比如 children_source: "[[news]]"。

卡片布局会使用每个子页面 frontmatter 中的 cover 图片。

排序#

sort 控制文件夹的子页面以何种顺序排列，进而决定卡片的外观。

---
title: 项目
sort: title
---

未声明 sort 时,moss 从子页面推断:

1. 任一子页面设了 weight → sort: weight
2. 80% 以上的子页面有 date → sort: date
3. 否则 → sort: title

因此多数文件夹都不需要声明 sort —— 博客文件夹自动是 date,带权重的文档自动是 weight,没有日期的项目集自动是 title。

为什么排序决定外观:日期排序的列表会在每张卡片的元数据槽位显示日期;权重和标题排序则不渲染元数据槽位(没有空白占位)。在非日期排序中,文件夹卡片仅在没有描述时显示小字号的"N 篇文章"副标题。

旧的 order: [...] 字段是 sort: [...] 的向后兼容别名。

媒体#

详见 media#Cover images。

版面#

控制页面正文的排版方向和宽度。

可以在文件夹的 cascade 中设置，应用到整个栏目：

---
title: 仪表板
cascade:
  content_width: full
---

交叉列表#

also_in 让一篇文章同时出现在多个栏目中，无需复制文件：

---
title: 搭建花架
also_in:
  - projects
  - featured
---

series 控制每篇子文章底部是否显示上一篇/下一篇导航。sort: weight (或显式列表) 的文件夹默认开启——因为有序的内容通常暗示连续阅读；sort: date 和 sort: title 默认关闭。可以显式覆盖：

# 一个按权重排序的参考文档,但不想要上一/下一导航
---
title: 参考
series: false
---

也可以在单篇文章自己的 frontmatter 设 series: false,让那一篇退出导航链。

高级字段#

Cascade#

cascade 将 frontmatter 值推送给所有后代页面，避免在每个文件中重复：

---
title: 文档
cascade:
  breadcrumb: true
  comments: false
---

这个页面下所有嵌套页面都会继承这些值，除非在自己的 frontmatter 中覆盖。