全局导航

全局导航（global nav）是文档中最左侧的面板。你可以使用全局导航来浏览内容。

研究表明，人们使用 Google 搜索 GitLab 产品文档。当他们访问搜索结果时，我们希望他们能找到与正在阅读内容相关的邻近主题。全局导航提供了这些信息。

在最高层级上，我们的全局导航是基于工作流的。导航需要帮助用户建立如何使用 GitLab 的心智模型。每个基于工作流的高层级主题下的层级是功能的名称。例如：

使用 GitLab（工作流）> 构建你的应用程序（工作流）> 入门（功能）> CI/CD（功能）> 流水线（功能）

尽管导航中的一些旧部分是按字母顺序排列的，但导航主要应基于工作流。

如果没有导航条目：

• 打开页面时导航会关闭，读者会失去位置。
• 该页面在其他页面组中不可见。

为你的导航条目选择正确的词语

在将项目添加到左侧导航之前，选择你想要使用的词性。

导航条目应与页面标题匹配。但是，如果标题太长，当你缩短短语时，请使用：

• 一个名词，如合并请求。
• 一个主动动词，如安装 GitLab 或入门 runners。

使用一个能清晰表明页面用途的短语。例如，入门不如入门 runners 有帮助。

添加导航条目

全局导航存储在 gitlab-org/technical-writing/docs-gitlab-com 项目的 data/en-us/navigation.yaml 文件中。docs.gitlab.com 上的文档网站使用 Hugo 构建，并从多个项目（包括 charts、gitlab、gitlab-runner 和 omnibus-gitlab）组装文档内容。

不要在没有技术写作者同意的情况下向全局导航添加项目。

要将主题添加到全局导航：

1. 检查该主题是否已发布在 https://docs.gitlab.com 上。
2. 在 navigation.yaml 文件中，添加该项目。
3. 将 MR 分配给技术写作者进行审查和合并。

在哪里添加

文档页面可以说属于以下组：

• GitLab 用户。此文档适用于任何权限级别（从 Reporter 到 Owner）的用户日常使用 GitLab。
• GitLab Admin。这通常是针对 GitLab 自托管实例的文档，需要访问托管 GitLab 的底层基础设施。
• 其他文档。这包括客户在日常使用 GitLab 之外的文档和贡献者的文档。不符合其他组的文档属于此处。

考虑到这些组，以下是新项目应添加位置的一般规则。

• 用户文档属于使用 GitLab。
• 管理（Admin）文档属于管理。
• 其他文档位于顶层，但必须注意不要创建过长的顶层导航，这违背了其目的。

使所有文档和导航项目都遵循这些原则正在逐步推出。

添加什么

在决定添加导航元素的位置后，下一步是决定添加什么。所需的技术细节在下方文档中，但原则上：

• 导航项目文本（读者看到的内容）应该：
  • 尽可能简短。
  • 具有上下文。很少需要重复父项目的文本。
  • 避免行话或专业术语，除非是普遍使用的。例如，CI 可以作为持续集成的替代词。
• 导航链接必须遵循数据文件中记录的规则。

你不需要添加的页面

从全局导航中排除这些页面：

• 法律声明。
• 位于 user/application_security/dast/checks/ 目录中的页面。

以下页面可能应该在全局导航中，但技术写作者不会主动添加它们：

• 位于 /development 目录中的页面。
• 由支持团队编写的页面，这些页面位于 doc/administration/troubleshooting 目录下。

有时功能页面必须从全局导航中排除。例如，对于已弃用功能的页面，根据功能被弃用的时间长短，可能不会出现在全局导航中。为了明确这些页面是有意从全局导航中排除的，请将以下代码添加到页面的前置信息中：

ignore_in_report: true

所有其他页面都应该在全局导航中。

技术写作团队运行报告以确定哪些页面不在导航中。该报告跳过在前置信息中带有 ignore_in_report: true 的页面。团队每月审查此列表。

使用 GitLab 部分

除了功能文档外，使用 GitLab 部分中的每个类别应包含：

• 一个顶层页面。
• 一个入门页面。

这确保了可重复的模式，让用户熟悉如何导航文档。

使用 GitLab 部分的结构是：

• 使用 GitLab
  • 顶层页面
    • 入门页面
    • 功能
    • 功能

组成

全局导航由两个文件构建：

• 数据
• 布局

数据文件为布局提供文档链接。布局在容器中正确样式化组织数据。

数据文件

数据文件描述了适用项目的导航结构。它存储在 https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml。

每个条目包含三个主要组件：

• title
• url
• submenu（可选）

例如：

- title: 入门
  url: 'user/get_started/'
- title: 教程
  url: 'tutorials/'
  submenu:
    - title: 熟悉 GitLab
      url: 'tutorials/gitlab_navigation/'
      submenu:
        - title: '教程：使用左侧边栏导航 GitLab'
          url: 'tutorials/left_sidebar/'

每个条目可以独立存在，也可以在 submenu 下包含嵌套页面。新组件缩进两个空格。

所有导航链接：

• 可选择。
• 必须引用唯一页面。
• 不得指向页面中的锚点，例如：path/to/page/#anchor-link。

必须遵循此规则，以避免重复链接或同时出现两个 .active 链接。

语法

对于所有组件，注意缩进并遵循以下语法规则。

标题

• 使用句子大小写，功能名称首字母大写。
• 无需包装标题，除非其中包含特殊字符。例如，在 GitLab CI/CD 中，存在 /，因此必须用引号包装。按照惯例，用双引号包装标题：title: "GitLab CI/CD"。

URL

URL 必须是相对的。此外：

• 每个 URL 以尾随 / 结尾（不是 .html 或 .md）。
• 不要以正斜杠 / 开头任何相对链接。
• 匹配你在网站上看到的路径。
• 按照惯例，始终用单引号包装 URL 'url'。要找到全局导航链接，从完整 URL 中删除 https://docs.gitlab.com/。
• 不要链接到外部 URL。通过点击左侧导航离开文档站点会造成混乱的用户体验。

相对 URL 示例：

布局文件（逻辑）

导航 Vue.js 组件 sidebar_menu.vue 由数据文件提供并构建全局导航。

全局导航包含来自所有五个上游项目的链接。全局导航 URL 根据你更改的文档文件具有不同的前缀。

CSS 类

导航在通用 main.css 文件中进行样式化。要更改其样式，请将它们分组以便团队更好地进行开发。

测试

我们在 check-navigation.sh 中对 navigation.yaml 运行各种检查，当 YAML 文件更新时，该脚本作为流水线作业运行。