YAML frontmatter 与可维护文档

写在正文之前

frontmatter 是许多文档工具约定的文件头，不是 CommonMark 基础语法。文件开头使用一对独立的 ---，中间写 YAML，然后开始正文。不同工具可能识别、忽略或显示这段信息。

---
title: 项目指南
description: 给新成员的本地文档
lang: zh-CN
tags: [入门, 文档]
authors: [Lin]
review_date: "2026-10-24"
---

标题、语言与标签都是内容的一部分。切换 Yeli 界面语言不会自动把 lang 改成英文；日期也不会自动更新。

YAML 容易踩的地方

冒号后有空格，层级使用空格而非 Tab；包含 : 、# 或易被解释为布尔/数字的文本时加引号。字段名不要重复。字符串列表和对象列表不是一回事；需要嵌套对象时先确认下游支持。

Yeli 属性表单能处理根级文本、有限数字、开关、日期字符串和字符串列表；复杂值保留只读，歧义 YAML 停用表单。未知安全字段不会因为没有专门界面就被丢弃。见文档属性。

给人和 Agent 的文档契约

在正文写目标、范围、来源、验收与下一步；元数据承载简短索引信息，不要把所有要求藏到字段中。稳定字段与清晰小节让工具容易定位，但敏感资料不会因写成 YAML 就安全，也不应把密钥放进公开手册。