技术文档项目中的YAML Frontmatter使用指南

技术文档项目中的YAML Frontmatter使用指南

docs The open-source repo for docs.github.com 项目地址: https://gitcode.com/gh_mirrors/do/docs

什么是YAML Frontmatter

YAML Frontmatter是一种在Markdown文件顶部添加元数据的标准方式，最初由Jekyll静态网站生成器推广。在技术文档项目中，它扮演着至关重要的角色，能够控制文档的版本、布局和各类元信息。

Frontmatter采用YAML格式编写，位于Markdown文件的最开始部分，用三个短横线---包裹起来。这种设计使得文档内容与元数据分离，便于系统处理和解析。

核心Frontmatter属性详解

版本控制(versions)

版本控制是技术文档中最关键的Frontmatter属性之一，它决定了文档适用于哪些产品版本。其特点包括：

• 类型：对象(Object)
• 必需属性：是
• 键值对应产品版本标识符
• 使用*表示适用于所有版本
• 支持版本范围表达式(如>=3.1 <3.3)

示例：

versions:
  fpt: '*'  # 适用于所有免费版
  ghes: '>=3.1 <3.3'  # 仅适用于企业版3.1到3.2

页面标题相关属性

1. title：设置页面主标题，用于HTML的<title>标签和页面顶部的<h1>元素

   • 类型：字符串
   • 可选，但建议始终设置

2. shortTitle：简短的标题变体，用于面包屑导航等空间有限的场景

   • 类型：字符串
   • 可选，未设置时使用title
   • 不同文章类型有最大长度限制(如普通文章31字符)

内容引导属性

1. intro：设置页面简介，显示在标题下方

   • 类型：字符串
   • 可选

2. permissions：设置权限说明，显示在简介下方

   • 类型：字符串
   • 可选

3. product：设置产品标注，显示在权限说明下方

   • 类型：字符串
   • 可选

布局与导航控制

1. layout：指定页面使用的布局模板

   • 类型：字符串(对应布局文件名)
   • 可选，默认为DefaultLayout

2. showMiniToc：控制是否显示自动生成的迷你目录

   • 类型：布尔值
   • 默认值：文章为true，索引页为false

3. children：列出属于当前产品/分类的子页面链接

   • 类型：数组
   • 在索引页(index.md)中必需

高级应用场景

创建产品指南页面

要创建专业的产品指南页面，需要组合使用多个Frontmatter属性：

layout: product-guides
learningTracks: getting_started,advanced_usage
includeGuides:
  - /path/to/guide1
  - /path/to/guide2

特殊内容处理

1. defaultPlatform：覆盖默认平台选择

   • 适用于需要特定平台默认值的场景(如Linux运行器)

2. defaultTool：覆盖默认工具选择

   • 可指定CLI、桌面端等不同工具偏好

3. changelog：集成变更日志

   • 自动从指定源拉取变更内容

最佳实践与注意事项

1. 文件名规范：

   • 使用kebab-case(短横线连接)命名文件
   • 文件名应与标题保持一致
   • 特殊情况可使用allowTitleToDifferFromFilename

2. 索引页管理：

   • 必须包含完整的children列表
   • 系统仅识别列在children中的路径

3. 特殊字符处理：

   • 单引号需转义为两个单引号('')
   • 或使用双引号包裹整个值

4. 内容分类：

   • 使用type和topics属性增强内容可发现性
   • 遵循已有的内容分类标准

通过合理运用YAML Frontmatter，技术文档作者能够精确控制文档的各个方面，从版本管理到布局设计，从而创建结构清晰、易于维护的专业文档体系。

docs The open-source repo for docs.github.com 项目地址: https://gitcode.com/gh_mirrors/do/docs