使用 YAML 前辅文

关于 YAML 前辅文

YAML 前辅文是由 Jekyll 推广的创作约定，它提供了向页面添加元数据的方法。 它是一个键值内容块，位于 GitHub Docs 内的每个 Markdown 文件的上方。 有关详细信息，请参阅 YAML frontmatter 文档。

YAML 前置内容值

以下前辅文值对 GitHub Docs 有特殊含义和要求。 测试套件还使用模式来验证每个页面的前置内容。 有关详细信息，请参阅 。

• versions
• redirect_from
• title
• shortTitle
• intro
• permissions
• product
• layout
• children
• childGroups
• featuredLinks
• showMiniToc
• allowTitleToDifferFromFilename
• changelog
• defaultPlatform
• defaultTool
• learningTracks
• includeGuides
• journeyTracks
• type
• topics
• communityRedirect
• effectiveDate

versions

• 目的：指示某页面适用的版本。 有关不同版本控制类型的更多信息，请参阅版本控制文档。
• 类型： 。 允许的键映射到产品名称，可在 的 对象中找到。
• 当前所有页面都需要前置信息值。
• 用于表示所有发布的版本。
• 必须为所有 文件提供，但实际值是在运行时根据子项计算的。

文档站点使用此前辅文值为每个文章版本生成“永久链接”。 有关详细信息，请参阅永久链接。

此示例适用于免费版、专业版、团队版，以及 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。
• 类型：
• 可选

示例：

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

有关详细信息，请参阅“AUTOTITLE”。

title

• 目的：设置用户友好的标题，以便在呈现页面的 标签和页面顶部的 元素中使用。
• 类型：
• 必填

shortTitle

• 目的：在痕迹导航和导航元素中使用的页标题缩写变体。
• 类型：
• 可选。 如果省略，将使用 。

文章类型	最大字符长度
文章	31
类别	27
映射主题	30

示例：

title: Contributing to projects with GitHub Desktop
shortTitle: Contributing to projects

intro

• 目的：设置页面简介。 此字符串将出现在 后。
• 类型：
• 可选。

permissions

• 目的：设置文章的权限声明。 此字符串将出现在 后。
• 类型：
• 可选。

product

• 目的：设置文章的产品标注。 此字符串将出现在“and”语句之后。
• 类型：
• 可选。

layout

• 目的：呈现正确的页面布局。
• 类型：与布局名称匹配的 。 对于命名 的布局，该值为 。
• 可选。 如果省略，将使用 。

children

• 目的：列出属于产品/类别/映射主题的相对链接。 有关详细信息，请参阅索引页。
• 类型： 。 默认值为 。
• 必须在页面上指定。

childGroups

• 目的：将子级呈现为主页上的组。 有关详细信息，请参阅主页。
• 键入：。 默认值为 。
• 主页 需要。

featuredLinks

• 目的：在产品登陆页和主页上呈现链接的文章标题和简介。
• 键入：。
• 可选。

热门链接列表是在登陆页上“热门”标题下方显示的链接。 或者，你可以通过将 属性设置为新字符串来自定义“热门”标题。

示例：

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。
• 键入：。 默认值为文章上的 、映射主题上的 和 页面。
• 可选。

allowTitleToDifferFromFilename

• 目的：指示是否允许页面有与其文件名不同的标题。 例如， 的标题为 而不是 。 具有此前辅文的页面被设置为 ，它不会在测试中标记或由 进行更新。
• 类型： 。 默认值为 。
• 可选。

changelog

• 目的：在产品登陆页上呈现从 GitHub Changelog拉取的项目列表（components/landing）。 “教育”是例外之一，从 拉取。
• 类型：，属性： * label -- 必须存在并对应于 GitHub Changelog 中使用的标签
  • -- 每个更改日志标题的开头可选字符串，这些字符串应在文档信息摘要中被省略。 例如，使用指定的前缀 GitHub Actions: ，GitHub Actions: Some Title Here 等更改日志标题将在文档源中呈现为 Some Title Here。
• 可选。

defaultPlatform

• 目的：替代页面的初始平台选择。 如果省略此前辅文，则默认显示与读者操作系统匹配的平台特定内容。 对于个别页面，此行为可被更改，手动选择将更加合理。 例如，大多数 GitHub Actions 运行器使用 Linux，它们的操作系统有别于读者的操作系统。
• 类型： ，其中一种：、、。
• 可选。

示例：

defaultPlatform: linux

defaultTool

• 目的：改写页面的初始工具选择，其中工具是指读者用于操作GitHub的应用程序（例如 GitHub.com 的 Web 界面、GitHub CLI 或 GitHub Desktop）或 GitHub API。 有关工具选择器的更多信息，请参阅 AUTOTITLE。 如果省略此 frontmatter，则默认显示与 GitHub Web UI 匹配的工具特定内容。 如果用户已指定工具偏好设置（通过单击工具选项卡），则将应用用户的偏好设置，而不是默认值。
• 类型：，其中一种：、、、、、、、、、、。
• 可选。

defaultTool: cli

learningTracks

• 目的：在产品的子登陆页上呈现学习轨迹列表。
• 类型： 。 这应该引用 中定义的学习轨迹名称。
• 可选

includeGuides

• 目的：呈现文章列表，可按 和 进行筛选。 仅在与 一起使用时适用。
• 类型：
• 可选。

示例：

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

• 目的：为着陆页面定义旅程。
• 类型： 具有以下属性的对象：
  • （必需）：旅程的唯一标识符。 ID 仅需对于同一旅程登录页中的旅程唯一。
  • （必需）：显示旅程标题（支持 Liquid 变量）
  • （可选）：旅程说明（支持 Liquid 变量）
  • （必需）：构成此旅程的指南对象的数组。 每个指南对象都有：
  • （必需）：文章的路径
  • （可选）：自定义文本，指导用户在旅程中的替代路径。 支持 Liquid 变量和 。
• 仅在与 一起使用时适用。
• 可选。

示例：

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

• 目的：指示文章的类型。
• 类型：，其中一种：、、、、、。
• 可选。

communityRedirect

• 目的：为页脚中的 Ask the GitHub community 链接设置自定义链接和链接名称。
• 类型： 。 属性为 和 。
• 可选。

effectiveDate

• 目的：为服务条款文章设置生效日期，因此工程团队可能再次提示用户确认条款
• 类型：年-月-日，如 2021-10-04 为 2021 年 10 月 4 日。
• 可选。

转义单引号

如果你在 YAML 前辅文的某行中看到两个单引号 ()，但你可能预期只看到一个 ()，则这是 YAML 进行单引号转义的偏好方式。

作为替代方式，你可以将前辅文字段外的单引号更改为双引号，保留内部单引号不转义。

自动生成的微型 TOC

每篇文章都展示一个迷你目录 (TOC)，这是自动生成的“本篇内容”部分，其中包含指向文章中所有章节的链接。 微型 TOC 仅包含 标题。 如果某文章使用 或 标题来划分信息，而且采用此方式时只有特定部分与具体任务相关，则你可以通过使用分区 TOC 帮助用户导航到与他们最相关的内容。

可以使用 前页值（设置为 ）来防止为某篇文章显示微型 TOC。

微型 TOC 不会显示在产品登陆页、类别登陆页或映射主题页上。

不要在 Markdown 源或显示重复微型 TOC 的其他页面上添加硬编码的“In this article”部分。

文件名

在添加新文章时，确保文件名是你在文章的 前辅文中所使用标题的短横线格式版本。 当标题包含标点符号（例如“GitHub的计费计划”）时，处理起来可能会变得棘手。 测试将标记标题和文件名之间的任何差异。 若要覆盖指定文章的此要求，你可以添加前言。

索引页

索引页是文档网站的目录文件。 每个产品、类别和地图主题子目录都有一个 文件，该文件提供了内容概述和每篇子文章的链接。 每个 必须包含 前辅文属性，以及指向产品、类别或映射主题子页的相对链接的列表。 索引页需要 前辅文属性，实际值将在运行时根据子文章版本计算。

主页

主页是文档站点的主目录文件。 主页必须有 的完整列表，如每个索引页，但还必须指定将在主内容区域高亮显示的 前辅文属性。

是一个映射数组，包含群组的 、群组的可选 以及 数组。 数组中的元素必须出现在 frontmatter 属性中。

创建新产品指南页

若要创建产品指南页（如GitHub Actions 指南页），使用以下特定的前辅文值创建或修改现有的 Markdown 文件：

• 通过引用<参考文献> 来使用产品指南页模板。
• 在 . 中包含学习路径。 可选。
• 定义 要包含哪些文章。 可选。

如果使用学习轨迹，需要在 中定义它们。 如果使用 ，确保此列表中的每篇文章都在其前页中包含 和 。