关于 YAML 前置信息
YAML 前置信息是 Jekyll 推广的一种创作约定，它提供了一种向页面添加元数据的方法。它是一个键值对内容块，位于 GitHub Docs 中每个 Markdown 文件的顶部。有关更多信息，请参阅 YAML 前置信息文档。
YAML 前置信息值
以下前置内容值对 GitHub 文档具有特殊含义和要求。测试套件还使用一个模式来验证每个页面的前置内容。有关更多信息，请参阅 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 |
| 类别 | 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，在地图主题和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 Changelog中提取的项目列表。唯一的例外是教育，它从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 Desktop）或 GitHub API。有关工具选择器的更多信息，请参阅“在 GitHub 文档中使用 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 中的特定属性设置。有关详细信息，请参阅该 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
- 目的：指示文章涵盖的主题。主题用于在某些登陆页面上过滤指南。例如，在“GitHub Actions 指南”底部，指南可以按主题过滤，主题列在指南简介下。有关添加主题的更多详细信息，请参阅内容模型。现有主题的完整列表位于 允许的主题文件 中。如果文章前置内容中的主题与允许的主题列表不同步，则 主题 CI 测试 将失败。
- 类型：
String数组 - 可选：每个文章都建议添加主题，但有些情况下，现有文章可能还没有主题，或者在新的文章中添加主题可能没有价值。
communityRedirect
- 目的：为页脚中的“询问 GitHub 社区”链接设置自定义链接和链接名称。
- 类型：
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。
文件名
添加新文章时，请确保文件名是文章中使用的标题的连字符大小写版本，该标题在文章的title前置信息中使用。当标题包含标点符号（例如“GitHub 的计费计划”）时，这可能会变得很棘手。测试将标记标题和文件名之间任何不一致的地方。要覆盖给定文章的此要求，您可以添加allowTitleToDifferFromFilename前置信息。
索引页面
索引页面是 Docs 网站的目录文件。每个产品、类别和地图主题子目录都有一个 `index.md` 文件，提供内容概述并链接到每个子文章。每个 `index.md` 必须包含一个 `children` 前端属性，其中包含指向产品、类别或地图主题子页面的相对链接列表。索引页面需要一个 `versions` 前端属性，实际值将在运行时根据子文章的版本计算得出。
**注意**：网站只知道 `children` 前端属性中包含的路径。如果目录或文章存在但**未**包含在 `children` 中，其路径将返回 404 错误。
主页
主页是 docs 网站的主要目录文件。主页必须包含完整的 `children` 列表，就像每个 索引页面 一样，但还必须指定 `childGroups` 前端属性，该属性将在主要内容区域中突出显示。
childGroups 是一个映射数组，包含组的 `name`、可选的组 `icon` 以及 `children` 数组。数组中的 `children` 必须存在于 `children` 前端属性中。
创建新的产品指南页面
要创建产品指南页面（例如 GitHub Actions 指南页面），请创建或修改现有 markdown 文件，并使用以下特定前端值。
- 通过引用 `layout: product-guides` 使用产品指南页面模板。
- 将学习轨迹包含在
learningTracks中。可选。 - 定义要包含的文章，使用
includeGuides。可选。
如果使用学习轨迹，则需要在 data/learning-tracks/*.yml 中定义。如果使用 `includeGuides`，请确保此列表中的每篇文章在其前端属性中都包含 topics 和 type。