关于 YAML 前辅文
YAML 前辅文是由 Jekyll 推广的创作约定，它提供了向页面添加元数据的方法。 它是一个键值内容块，位于 GitHub Docs 内的每个 Markdown 文件的上方。 有关详细信息，请参阅 YAML 前辅文文档。
YAML 前置内容值
以下前辅文值对 GitHub Docs 有特殊含义和要求。
测试套件还使用模式来验证每个页面的前置内容。
有关详细信息，请参阅 lib/frontmatter.ts。
versionsredirect_fromtitleshortTitleintropermissionsproductlayoutchildrenchildGroupsfeaturedLinksshowMiniTocallowTitleToDifferFromFilenamechangelogdefaultPlatformdefaultToollearningTracksincludeGuidesjourneyTrackstypecommunityRedirecteffectiveDate
versions
- 目的：指示某页面适用的版本。 有关不同版本控制类型的更多信息，请参阅版本控制文档。
- 类型：
Object。 允许的键映射到产品名称，可在versions的lib/frontmatter.ts对象中找到。 - 当前需要这个辅文值来用于所有页面。
-
`*` 用于表示该版本的所有发布。 - 必须存在于所有
index.md文件中，但实际值是在运行时根据子元素计算的。
文档站点使用此前辅文值为每个文章版本生成“永久链接”。 有关详细信息，请参阅永久链接。
此示例适用于免费版、专业版、团队版，以及 GitHub Enterprise Server 3.11版及更高版本。
title: About your personal dashboard
versions:
fpt: '*'
ghes: '>=3.11'
仅适用于 GitHub Enterprise Server 的示例：
title: Downloading your license
versions:
ghes: '*'
还可对一系列发布的页面进行版本控制。 这仅会对免费版、专业版、& 团队版以及 GitHub Enterprise Server 版本 3.1 和 3.2 的页面进行版本控制：
versions:
fpt: '*'
ghes: '>=3.1 <3.3'
redirect_from
- 目的：列出应重定向到此页面的 URL。
- 类型：
Array - 可选
示例：
title: Getting started with GitHub Desktop
redirect_from:
- /articles/first-launch
- /articles/error-github-enterprise-version-is-too-old
- /articles/getting-started-with-github-for-windows
有关详细信息，请参阅“配置重定向”。
title
- 目的：设置用户友好的标题，以便在呈现页面的
<title>标签和页面顶部的h1元素中使用。 - 类型：
String -
**必需**。
shortTitle
- 目的：在痕迹导航和导航元素中使用的页标题缩写变体。
- 类型：
String - 可选。 如果省略，将使用
title。
| 文章类型 | 最大字符长度 |
|---|---|
| 文章 | 31 |
| 类别 | 27 |
| 映射主题 | 30 |
示例：
title: Contributing to projects with GitHub Desktop
shortTitle: Contributing to projects
intro
- 目的：设置页面简介。 此字符串将出现在
title后。 - 类型：
String - 可选。
permissions
- 目的：设置文章的权限声明。 此字符串将出现在
intro后。 - 类型：
String - 可选。
product
- 目的：设置文章的产品标注。 此字符串将出现在
intro和permissions语句后。 - 类型：
String - 可选。
layout
- 目的：呈现正确的页面布局。
- 类型：与布局名称匹配的
String。 对于命名components/landing的布局，该值为product-landing。 - 可选。 如果省略，将使用
DefaultLayout。
children
- 目的：列出属于产品/类别/映射主题的相对链接。 有关详细信息，请参阅索引页。
- 类型：
Array。 默认值为false。 -
`index.md` 页面需要。
childGroups
- 目的：将子级呈现为主页上的组。 有关详细信息，请参阅主页。
- 类型：
Array。 默认值为false。 - 主页上需要
index.md。
featuredLinks
- 目的：在产品登陆页和主页上呈现链接的文章标题和简介。
- 类型：
Object。 - 可选。
热门链接列表是在登陆页上“热门”标题下方显示的链接。 或者，你可以通过将 featuredLinks.popularHeading 属性设置为新字符串来自定义“热门”标题。
示例：
featuredLinks:
gettingStarted:
- /path/to/page
startHere:
- /guides/example
popular:
- /path/to/popular/article1
- /path/to/popular/article2
popularHeading: An alternate heading to Popular
showMiniToc
- 目的：指示文章是否应在其余内容上方显示微型目录 (TOC)。 有关详细信息，请参阅自动生成的微型 TOC。
- 类型：
Boolean。 默认值为文章的true、地图主题的false和index.md页面的默认值。 - 可选。
allowTitleToDifferFromFilename
- 目的：指示是否允许页面有与其文件名不同的标题。 例如，
content/rest/reference/orgs.md的标题为Organizations而不是Orgs。 具有此前置字段设置为true的页面不会在测试中被标记，也不会被src/content-render/scripts/reconcile-filenames-with-ids.ts进行更新。 - 类型：
Boolean。 默认值为false。 - 可选。
changelog
- 目的：在产品登陆页上呈现从 GitHub Changelog拉取的项目列表（
components/landing）。 “教育”是唯一的例外，从 https://github.blog/category/community/education 中提取。 - 类型：
Object，属性： *label-- 必须存在并对应于 GitHub Changelog 中使用的标签 *prefix-- 每个更改日志标题的开头可选字符串，这些字符串应在文档信息摘要中被省略。 例如，使用指定的前缀GitHub Actions:，GitHub Actions: Some Title Here等更改日志标题将在文档源中呈现为Some Title Here。 - 可选。
defaultPlatform
- 目的：替代页面的初始平台选择。 如果省略此前辅文，则默认显示与读者操作系统匹配的平台特定内容。 对于个别页面，此行为可被更改，手动选择将更加合理。 例如，大多数 GitHub Actions 运行器使用 Linux，它们的操作系统有别于读者的操作系统。
- 类型：
String，其中一种：mac、windows、linux。 - 可选。
示例：
defaultPlatform: linux
defaultTool
- 目的：覆盖页面的默认工具选择，这里的工具是指用户用来处理GitHub的应用程序（例如 GitHub.com 的 Web UI、GitHub CLI 或 GitHub 桌面）或 GitHub API。 有关工具选择器的详细信息，请参阅在 GitHub Docs 中使用 Markdown 和 Liquid。 如果省略此 frontmatter，则默认显示与 GitHub Web 界面匹配的工具特定内容。 如果用户已指定工具偏好设置（通过单击工具选项卡），则将应用用户的偏好设置，而不是默认值。
- 类型：
String，其中一种：webui、cli、desktop、curl、codespaces、vscode、importer_cli、graphql、powershell、bash、javascript。 - 可选。
defaultTool: cli
learningTracks
- 目的：在产品的子登陆页上呈现学习轨迹列表。
- 类型：
String。 这应该引用data/learning-tracks/*.yml中定义的学习轨迹名称。 - 可选
注意
指定的轨道是由学习路径 YAML 中的特定属性设置的。 有关详细信息，请参阅自述文件。
includeGuides
- 目的：呈现文章列表，可按
type和topics进行筛选。 仅在与layout: product-guides一起使用时适用。 - 类型：
Array - 可选。
示例：
includeGuides:
- /actions/guides/about-continuous-integration
- /actions/guides/setting-up-continuous-integration-using-workflow-templates
- /actions/guides/building-and-testing-nodejs
- /actions/guides/building-and-testing-powershell
journeyTracks
- 目的：为着陆页面定义旅程。
- 类型：
Array具有以下属性的对象： *id（必需）：旅程的唯一标识符。 ID 仅需对于同一旅程登录页中的旅程唯一。 *title（必需）：显示旅程标题（支持 Liquid 变量） *description（可选）：旅程说明（支持 Liquid 变量） *guides（必需）：构成此旅程的指南对象的数组。 每个指南对象都有： *href（必需）：文章的路径 *alternativeNextStep（可选）：自定义文本，指导用户在旅程中的替代路径。 支持 Liquid 变量和[AUTOTITLE]。 - 仅在与
layout: journey-landing一起使用时适用。 - 可选。
示例：
journeyTracks:
- id: 'getting_started'
title: 'Getting started with GitHub Actions'
description: 'Learn the basics of GitHub Actions.'
guides:
- href: '/actions/quickstart'
- href: '/actions/learn-github-actions'
alternativeNextStep: 'Want to skip ahead? See [AUTOTITLE](/actions/using-workflows).'
- href: '/actions/using-workflows'
- id: 'advanced'
title: 'Advanced GitHub Actions'
description: 'Dive deeper into advanced features.'
guides:
- href: '/actions/using-workflows/workflow-syntax-for-github-actions'
- href: '/actions/deployment/deploying-with-github-actions'
type
- 目的：指示文章的类型。
- 类型：
String，其中一种：overview、quick_start、tutorial、how_to、reference、rai。 - 可选。
communityRedirect
- 目的：为页脚中的
Ask the GitHub community链接设置自定义链接和链接名称。 - 类型：
Object。 属性为name和href。 - 可选。
effectiveDate
- 目的：为服务条款文章设置生效日期，因此工程团队可能再次提示用户确认条款
- 类型：
string年-月-日，如 2021-10-04 为 2021 年 10 月 4 日。 - 可选。
注意
`effectiveDate` 前辅文值仅供 GitHub 员工使用。
转义单引号
如果你在 YAML 前置数据中看到两个单引号 ('')，而你可能只预期看到一个 (')，那么这是 YAML 转义单引号的首选方式。
作为替代方式，你可以将前辅文字段外的单引号更改为双引号，保留内部单引号不转义。
自动生成的微型 TOC
每篇文章都会显示一个微型目录 (TOC)，即自动生成的“本文内容”部分，该部分包含指向文章中所有 H2 的链接。 微型 TOC 仅包含 H2 标题。 如果某文章使用 H3 或 H4 标题来划分信息，而且采用此方式时只有特定部分与具体任务相关，则你可以通过使用分区 TOC 帮助用户导航到与他们最相关的内容。
你可以使用 showMiniToc 前辅文值（设置为 false）来防止为某篇文章显示微型 TOC。
微型 TOC 不会显示在产品登陆页、类别登陆页或映射主题页上。
不要在 Markdown 源或显示重复微型 TOC 的其他页面上添加硬编码的“In this article”部分。
文件名
在添加新文章时，确保文件名是你在文章的 前辅文中所使用标题的title版本。 当标题具有标点符号（如“GitHub的计费计划”）时，这可能会变得棘手。 测试将标记标题和文件名之间的任何差异。 若要替代特定文章的此要求，你可以添加 allowTitleToDifferFromFilename 前置内容。
索引页
索引页是文档网站的目录文件。 每个产品、类别和地图主题子目录都有一个 index.md 文件，该文件提供了内容概述和每篇子文章的链接。 每个 index.md 必须包含一个 children 前置属性，带有指向产品、类别或映射主题子页的相对链接的列表。 索引页需要 versions 前辅文属性，实际值将在运行时根据子文章版本计算。
注意
站点只能识别包含在 children 元数据中的路径。 如果某目录或文章存在，但不包含在 children 当中，它的路径将返回 404。
主页
主页是文档站点的主目录文件。 主页必须有children的完整列表，如每个索引页，但还必须指定将在主内容区域中将会高亮显示的childGroups前置元数据属性。
`childGroups` 是一个映射数组，包含群组的 `name`、群组的可选 `icon` 以及 `children` 数组。 数组中的 `children` 必须出现在 `children` 前辅文属性中。
创建新产品指南页
若要创建产品指南页（如GitHub Actions 指南页），使用以下特定的前辅文值创建或修改现有的 Markdown 文件：
- 通过引用
layout: product-guides来使用产品指南页模板。 - 在
learningTracks中包含学习轨迹。 可选。 - 定义要用
includeGuides包含哪些文章。 可选。
如果使用学习轨迹，需要在 data/learning-tracks/*.yml 中定义它们。
如果使用includeGuides，请确保此列表中的每篇文章的前端都有type。