关于 YAML 前端内容
YAML 前端内容是由 Jekyll 推广的一种创作约定，它提供了一种向页面添加元数据的方法。它是位于每个 GitHub 文档 Markdown 文件顶部的键值内容块。有关更多信息，请参阅YAML 前端内容文档。
YAML 前端内容值
以下前端内容值对 GitHub 文档具有特殊的含义和要求。测试套件还使用一个模式来验证每个页面的前端内容。有关更多信息，请参阅lib/frontmatter.js。
versionsredirect_fromtitleshortTitleintropermissionsproductlayoutchildrenchildGroupsfeaturedLinksshowMiniTocallowTitleToDifferFromFilenamechangelogdefaultPlatformdefaultToollearningTracksincludeGuidestypetopicscommunityRedirecteffectiveDate
versions
- 用途：指示页面适用的版本。有关不同类型的版本控制的更多信息，请参阅“版本控制文档”。
- 类型：
Object。允许的键映射到产品名称，可以在lib/frontmatter.js中的versions对象中找到。 - 此前端内容值目前对所有页面都是**必需的**。
*用于表示版本的全部版本。- 对于所有
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 - 可选。如果省略，页面
<title>仍将设置，尽管使用的是通用的值，例如GitHub.com或GitHub Enterprise。
shortTitle
- 用途：页面标题的简略变体，用于面包屑和导航元素。
- 类型：
String - 可选。如果省略，将使用
title。
| 文章类型 | 最大字符长度 |
|---|---|
| articles | 31 |
| categories | 27 |
| map topics | 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)。有关更多信息，请参阅自动生成的迷你目录。
- 类型：
Boolean。在文章中默认为true，在地图主题和index.md页面中默认为false。 - 可选。
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-- 可选字符串，用于每个更新日志标题的开头，但在文档 Feed 中应省略。例如，指定前缀GitHub Actions:后，类似GitHub Actions: Some Title Here的更新日志标题将在文档 Feed 中显示为Some Title Here。
- 可选。
defaultPlatform
- 用途：覆盖页面的初始平台选择。如果省略此 frontmatter，则默认显示与读者操作系统匹配的特定平台内容。此行为可以针对各个页面进行更改，对于这些页面，手动选择更合理。例如，大多数 GitHub Actions 运行器使用 Linux，其操作系统独立于读者的操作系统。
- 类型：
String，取值范围：mac、windows、linux。 - 可选。
示例
defaultPlatform: linux
defaultTool
- 用途：覆盖页面的初始工具选择，其中工具指读者用来与 GitHub 协作的应用程序（例如 GitHub.com 的 Web UI、GitHub CLI 或 GitHub Desktop）或 GitHub API。有关工具选择器的更多信息，请参阅“在 GitHub 文档中使用 Markdown 和 Liquid”。如果省略此 frontmatter，则默认显示与 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 中的特定属性设置。有关详细信息，请参阅该README。
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
- 用途：指示文章涵盖的主题。有关添加主题的更多详细信息，请参阅内容模型。现有主题的完整列表位于允许的主题文件中。如果文章 frontmatter 中的主题和允许主题列表不同步，则主题 CI 测试将失败。
- 类型：
String数组 - 可选：每个文章都首选主题，但是，在某些情况下，现有文章可能还没有主题，或者向新文章添加主题可能不会增加价值。
communityRedirect
- 用途：为页脚中的“询问 GitHub 社区”链接设置自定义链接和链接名称。
- 类型：
Object。属性为name和href。 - 可选。
effectiveDate
- 用途：为服务条款文章设置生效日期，以便工程团队可以自动重新提示用户确认条款。
- 类型：
string年-月-日，例如 2021-10-04 为 2021 年 10 月 4 日。 - 可选。
注意
effectiveDate frontmatter 值仅供 GitHub 员工使用。
转义单引号
如果您在 YAML frontmatter 中看到两个连续的单引号（''），而您可能期望看到一个单引号（'），这是 YAML 首选的转义单引号的方法。
或者，您可以将围绕 frontmatter 字段的单引号更改为双引号，并保留未转义的内部单引号。
自动生成的迷你 TOC
每篇文章都会显示一个迷你目录 (TOC)，这是一个自动生成的“本文档包含”部分，其中包含指向文章中所有H2的链接。迷你 TOC 中仅包含H2标题。如果文章使用H3或H4标题来划分信息，而只有某些部分与特定任务相关，则您可以通过使用分节 TOC帮助人们导航到与他们最相关的內容。
您可以使用设置为false的showMiniToc frontmatter 值来阻止迷你 TOC 显示在文章中。
迷你 TOC 不会出现在产品目标网页、类别目标网页或地图主题页面上。
不要在 Markdown 源代码中添加硬编码的“本文档包含”部分，否则页面将显示重复的迷你 TOC。
文件名
添加新文章时，请确保文件名是文章title frontmatter 中使用的标题的kebab-case 版本。当标题包含标点符号（例如“GitHub 的计费计划”）时，这可能会变得棘手。测试将标记标题和文件名之间任何不一致之处。要为给定文章覆盖此要求，您可以添加allowTitleToDifferFromFilename frontmatter。
索引页
索引页是 Docs 站点的目录文件。每个产品、类别和地图主题子目录都有一个index.md文件，该文件提供内容概述以及指向每个子文章的链接。每个index.md必须包含一个children frontmatter 属性，其中包含指向产品、类别或地图主题子页面的相对链接列表。索引页需要一个versions frontmatter 属性，实际值将在运行时根据子文章的版本计算。
注意
站点只知道children frontmatter 中包含的路径。如果目录或文章存在但**未**包含在children中，则其路径将返回 404。
主页
主页是文档站点的主要目录文件。主页必须包含完整的children列表，就像每个索引页一样，但还必须指定将在主要内容区域中突出显示的childGroups frontmatter 属性。
childGroups是一个映射数组，包含组的name、组的可选icon以及children数组。数组中的children必须存在于children frontmatter 属性中。
创建新的产品指南页面
要创建产品指南页面（例如GitHub Actions 指南页面），请创建或修改具有这些特定 frontmatter 值的现有 markdown 文件。
- 通过引用
layout: product-guides使用产品指南页面模板。 - 在
learningTracks中包含学习路径。可选。 - 使用
includeGuides定义要包含的文章。可选。
如果使用学习路径，则需要在data/learning-tracks/*.yml中定义它们。如果使用includeGuides，请确保此列表中的每篇文章在其 frontmatter 中都有topics和type。