使用 YAML 前置数据

关于 YAML 前置数据

YAML 前置数据是一种由 Jekyll 推广的创作约定，提供向页面添加元数据的方式。它是位于 GitHub 文档中每个 Markdown 文件顶部的键值块。欲了解更多信息，请参阅 YAML 前置数据文档。

YAML 前置数据值

以下前置数据值在 GitHub 文档中具有特殊含义和要求。还有一个由测试套件使用的模式，用于验证每个页面的前置数据。欲了解更多信息，请参阅 lib/frontmatter.ts。

• versions

• redirect_from

• title

• shortTitle

• intro

• permissions

• product

• layout

• children

• childGroups

• featuredLinks

• showMiniToc

• allowTitleToDifferFromFilename

• changelog

• defaultPlatform

• defaultTool

• journeyTracks

• type

• communityRedirect

• effectiveDate

versions

• 目的：指示页面适用于哪个 版本。有关不同版本类型的更多信息，请参阅 版本文档。
• 类型：Object。允许的键映射到产品名称，可在 lib/frontmatter.ts 中的 versions 对象找到。
• 此前置数据值目前对所有页面都是 必需 的。
• * 用于表示该版本的所有发布。
• 必须出现在所有 index.md 文件中，但实际值在运行时根据子页面计算得出。

此前置数据值被文档站点用于为文章的每个版本生成“永久链接”。欲了解更多信息，请参阅 永久链接。

适用于 Free、Pro、Team 以及 GitHub Enterprise Server 3.11 及更高版本的示例

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=3.11'

仅适用于 GitHub Enterprise Server 的示例

title: Downloading your license
versions:
  ghes: '*'

您也可以为一系列发布进行页面版本管理。这将仅为 Free、Pro、Team 以及 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）。更多信息，请参阅 自动生成的小型目录。
• 类型：Boolean。默认在文章上为 true，在映射主题和 index.md 页面上为 false。
• 可选。

allowTitleToDifferFromFilename

• 目的：指示页面的标题是否可以与文件名不同。例如，content/rest/reference/orgs.md 的标题为 Organizations 而非 Orgs。将此前置数据设为 true 的页面不会在测试中被标记，也不会被 src/content-render/scripts/reconcile-filenames-with-ids.ts 更新。
• 类型：Boolean。默认值为 false。
• 可选。

changelog

• 目的：在产品登录页面（components/landing）上渲染从 GitHub 更新日志 抓取的项目列表。唯一例外是 Education，它从 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 Web UI 匹配的工具特定内容。如果用户已通过点击工具标签指明了工具偏好，则会使用用户的偏好而非默认值。
• 类型：String，可选值：webui、cli、desktop、curl、codespaces、vscode、importer_cli、graphql、powershell、bash、javascript。
• 可选。

defaultTool: cli

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 YEAR-MONTH-DAY，例如 2021-10-04 表示 2021 年 10 月 4 日。
• 可选。

转义单引号

如果在 YAML 前置数据中看到连续的两个单引号（'''），这就是 YAML 推荐的转义单引号的方式。

作为替代方案，您可以将前置数据字段两侧的单引号改为双引号，内部的单引号则保持不转义。

自动生成的小型目录

每篇文章都会显示一个小型目录（TOC），这是一个自动生成的“本文内容”章节，包含文章中所有 H2 的链接。仅 H2 标题会出现在小型目录中。如果文章使用 H3 或 H4 标题来划分信息，而只有特定章节与某项任务相关，您可以通过使用 分节目录 来帮助读者快速定位最相关的内容。

您可以使用 showMiniToc 前置数据并将其设为 false，以阻止文章显示小型目录。

小型目录不会出现在产品登录页面、分类登录页面或映射主题页面上。

不要在 Markdown 源文件中手动添加“本文内容”章节，否则页面会显示重复的小型目录。

文件名

在添加新文章时，请确保文件名是标题在 kebab‑case 形式的对应版本。例如标题为 “GitHub's Billing Plans”。如果标题包含标点符号，可能会比较棘手。测试会标记标题与文件名不匹配的情况。若需为特定文章覆盖此要求，可在前置数据中添加 allowTitleToDifferFromFilename。

索引页面

索引页面是文档站点的目录文件。每个产品、分类和映射主题子目录都有一个 index.md 文件，用于概述内容并链接到每篇子文章。每个 index.md 必须包含 children 前置数据属性，列出指向该产品、分类或映射主题子页面的相对链接。索引页面需要 versions 前置数据属性，其实际值将在运行时依据子文章的版本计算。

首页

首页是文档站点的主目录文件。首页必须拥有完整的 children 列表，类似每个 索引页面，但同时必须指定将在主内容区域突出显示的 childGroups 前置数据属性。

childGroups 是一个映射数组，每个映射包含该组的 name、可选的 icon，以及一个 children 数组。数组中的 children 必须出现在 children 前置数据属性中。