Help us learn about your current experience with the documentation. Take the survey.

元数据

每个文档 Markdown 页面都包含 YAML front matter。元数据中的所有值都被视为字符串，仅用于文档网站。

阶段和组元数据

每个页面都应包含与其所属阶段和组相关的元数据、信息块和页面标题。例如：

---
stage: Example Stage
group: Example Group
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
title: Example page title
---

要填充元数据，请包含以下信息：

stage: 页面内容主要属于的 Stage。
group: 页面内容主要属于的 Group。
info: 如何找到与页面阶段和组相关的 Technical Writer。
title: 出现在页面顶部的 H1（一级标题）的页面标题。

异常情况

/development 目录中的文档会获得以下元数据：

---
stage: Example Stage
group: Example Group
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/development/development_processes/#development-guidelines-review.
title: Example page title
---

/solutions 目录中的文档会获得以下元数据：

---
stage: Solutions Architecture
group: Solutions Architecture
info: This page is owned by the Solutions Architecture team.
title: Example page title
---

标题元数据

title 元数据：

在渲染后的页面顶部生成 H1（一级标题）。
可用于生成自动页面列表。
替换 Markdown H1 标题（如 # 页面标题）。

描述元数据

description 标签：

用于填充文档主页上的文本。
在社交媒体预览中显示。
可用于搜索结果片段。
当页面包含在 cards shortcode 中时显示。

对于顶级页面，如 Use GitLab 及其下一级页面，描述是名词列表。例如，对于 Set up your organization，描述是 Users, groups, namespaces, SSH keys。

对于其他页面，描述不主动维护。但是，如果您想添加描述，请使用关于页面内容的简短描述。有关提示，请参阅 Google 创建高质量 meta 描述的最佳实践。

避免页面被添加到全局导航

如果特定页面不应添加到全局导航（在 navigation.yaml 中添加条目），请将以下内容添加到页面的元数据中：

ignore_in_report: true

当页面上设置此元数据时：

pages_not_in_nav.cjs 脚本在处理文档时会忽略该页面。
执行技术写作团队月度任务的技术写作人员不会收到将页面添加到全局导航的提示。

指示 GitLab Dedicated 支持

gitlab_dedicated 元数据指示文档页面是否适用于 GitLab Dedicated。

当产品团队确认了 GitLab Dedicated 的可用性状态后，将此字段添加到文档页面。此元数据应补充，而不是替换 Offering 详细信息中的信息。

例如，通常适用于 GitLab Self-Managed 的页面也适用于 GitLab Dedicated。当它们不适用时，使用此元数据：

gitlab_dedicated: no

当页面适用于 GitLab Dedicated 时，使用：

gitlab_dedicated: yes

对于在 GitLab Dedicated 上部分可用的页面，使用 gitlab_dedicated: yes 并更新不适用于 GitLab Dedicated 的任何主题的产品可用性详细信息。

指示缺少产品可用性详细信息

在故意不包含可用性详细信息的页面上，将此元数据添加到页面顶部：

availability_details: no

其他元数据

以下元数据是可选的，不主动维护。

feedback：设置为 false 以不包含"帮助与反馈"页脚。
noindex：设置为 true 以防止搜索引擎索引该页面。
redirect_to：用于控制重定向。有关更多信息，请参阅 GitLab 文档中的重定向。
searchbar：设置为 false 以不包含页面标题中的搜索栏。
toc：设置为 false 以不包含"在此页面上"导航。

TW 元数据的批量更新

CODEOWNERS 文件包含文件列表和相关的技术写作人员。

当合并请求包含文档时，CODEOWNERS 文件中的信息会确定：

Approvers 部分中的用户列表。
GitLab Bot 为社区贡献 ping 的技术写作人员。

您可以使用 Rake 任务来更新 CODEOWNERS 文件。

更新 `CODEOWNERS` 文件

当组或 TW 分配更改时，您必须更新 CODEOWNERS 文件。为此，您需要运行 codeowners.rake Rake 任务。此任务检查 doc 目录中的所有文件，读取元数据，并使用 codeowners.rake 文件中的信息来填充 CODEOWNERS 文件。

要更新 CODEOWNERS 文件：

如有必要，更新任何受影响的文档页面的阶段和组元数据。如果有很多更改，您可以在单独的 MR 中执行此步骤。
使用更改更新 codeowners.rake 文件。
进入 gitlab 仓库的根目录。
使用以下命令运行 Rake 任务：bundle exec rake tw:codeowners
检查 CODEOWNERS 文件中的更改。
添加并提交所有更改，并将您的分支推送到 origin。
创建合并请求并将其分配给技术写作经理进行审核。

当您更新 codeowners.rake 文件时：

要为单个组指定多个写作人员，请在写作人员名称之间使用空格。文件会分配给两个写作人员。
```
CodeOwnerRule.new('Group Name', '@writer1 @writer2'),
```
要将组中的不同写作人员分配到不同目录的文档，请使用 path 参数指定目录：
```
CodeOwnerRule.new('Group Name', ->(path) { path.start_with?('/doc/user') ? '@writer1' : '@writer2' }),
```
在此示例中，writer1 是 /doc/user 中与此组相关的文件的代码所有者。对于其他所有内容，writer2 被设为代码所有者。有关示例，请参阅 MR 127903。
对于没有分配写作人员的组，在文件中包含组名并注释掉该行：
```
# CodeOwnerRule.new('Group Name', ''),
```

元数据