关于 YAML 前辅文
YAML 前辅文是由 Jekyll 推广的创作约定，它提供了向页面添加元数据的方法。 它是一个键值内容块，位于 GitHub Docs 内的每个 Markdown 文件的上方。 有关详细信息，请参阅 YAML 前辅文文档。
YAML 前辅文值
以下前辅文值对 GitHub Docs 有特殊含义和要求。
测试套件还使用架构来验证每个页面的前辅文。
有关详细信息，请参阅 lib/frontmatter.js。
versionsredirect_fromtitleshortTitleintropermissionsproductlayoutchildrenchildGroupsfeaturedLinksshowMiniTocallowTitleToDifferFromFilenamechangelogdefaultPlatformdefaultToollearningTracksincludeGuidestypetopicscommunityRedirecteffectiveDate
versions
- 目的：指示某页面适用的版本。 有关不同版本控制类型的更多信息，请参阅版本控制文档。
- 键入：
Object。 允许的键映射到产品名称，可在lib/frontmatter.js的versions对象中找到。 - 当前所有页面都需要此前辅文值。
*用于表示所有发布的版本。- 必须为所有
index.md文件提供，但实际值是在运行时根据子项计算的。
文档站点使用此前辅文值为每个文章版本生成“永久链接”。 有关详细信息，请参阅永久链接。
适用于 GitHub.com 和 GitHub Enterprise Server 近期版本的示例：
title: About your personal dashboard
versions:
fpt: '*'
ghes: '>=3.11'
适用于 GitHub Enterprise Server 的所有受支持版本，但不适用于 GitHub.com 的示例：
title: Downloading your license
versions:
ghes: '*'
还可对一系列发布的页面进行版本控制。 这仅会对 GitHub.com 和 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 - 可选。 如果省略，仍将设置页面
<title>，而不管是否有GitHub.com或GitHub Enterprise等泛型值。
shortTitle
- 目的：在痕迹导航和导航元素中使用的页标题缩写变体。
- 类型：
String - 可选。 如果省略，将使用
title。
| 文章类型 | 最大字符长度 |
|---|---|
| 文章 | 31 |
| Categories | 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.js进行更新。 - 键入：
Boolean。 默认值为false。 - 可选。
changelog
- 目的：在产品登陆页 (
components/landing) 上呈现从 GitHub 更改日志拉取的项目列表。 “教育”是例外之一，从 https://github.blog/category/community/education 拉取。 - 类型：
Object，属性：label-- 必须存在并且与 GitHub 更改日志中使用的标签对应。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 Desktop）或 GitHub API 搭配使用的应用程序。 有关选择更改的详细信息，请参阅“在 GitHub Docs 中使用 Markdown 和 Liquid”。 如果省略此前辅文，则默认显示与 GitHub Web UI 匹配的工具特定内容。 如果用户已指定工具偏好设置（通过单击工具选项卡），则将应用用户的偏好设置，而不是默认值。
- 类型：
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
type
- 目的：指示文章的类型。
- 类型：
String，其中一种：overview、quick_start、tutorial、how_to、reference、rai。 - 可选。
topics
- 目的：指示文章涵盖的主题。 这些主题用于筛选某些登陆页上的指南。 例如，《GitHub Actions 指南》底部的指南可按主题进行筛选，主题列在指南简介下方。 有关添加主题的详细信息，请参阅内容模型。 现有主题的完整列表位于“允许的主题文件”当中。 如果文章前辅文和允许主题列表中的主题不同步，主题 CI 测试将会失败。
- 类型：
String的数组 - 可选：每篇文章的偏好设置有主题，但现有文章有可能还没有主题，或为新文章添加主题可能不会添加值。
communityRedirect
- 目的：为页脚中的
Ask the GitHub community链接设置自定义链接和链接名称。 - 键入：
Object。 属性为name和href。 - 可选。
effectiveDate
- 目的：为服务条款文章设置生效日期，因此工程团队可能再次提示用户确认条款
- 类型：
string年-月-日，如 2021-10-04 为 2021 年 10 月 4 日。 - 可选。
注意：effectiveDate 前辅文值仅供 GitHub 员工使用。
转义单引号
如果你在 YAML 前辅文的某行中看到两个单引号 ('')，但你可能预期只看到一个 (')，则这是 YAML 进行单引号转义的偏好方式。
作为替代方式，你可以将前辅文字段外的单引号更改为双引号，保留内部单引号不转义。
自动生成的微型 TOC
每篇文章都显示一个微型目录 (TOC)，它是自动生成的“In this article”部分，其中包含指向文章中所有 H2 的链接。 微型 TOC 仅包含 H2 标题。 如果某文章使用 H3 或 H4 标题来划分信息，而且采用此方式时只有特定部分与具体任务相关，则你可以通过使用分区 TOC 帮助用户导航到与他们最相关的内容。
你可以使用 showMiniToc 前辅文值（设置为 false）来防止为某篇文章显示微型 TOC。
微型 TOC 不会显示在产品登陆页、类别登陆页或映射主题页上。
不要在 Markdown 源或显示重复微型 TOC 的其他页面上添加硬编码的“In this article”部分。
文件名
在添加新文章时，确保文件名是你在文章的 title 前辅文中所使用标题的短横线格式版本。 如果标题中有标点符号（如“GitHub's Billing Plans”），情况可能变得有点棘手。 测试将标记标题和文件名之间的任何差异。 若要替代指定文章的此要求，你可以添加 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，确保此列表中的每篇文章都在它的前辅文中包含 topics 和 type。