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

Hugo 迁移参考指南（面向作者）

我们已使用 Hugo 重建了 GitLab Docs 网站。本指南概述了重新发布后文档的格式要求。

虽然现有内容将自动更新，但任何新文档或修改后的文档都必须遵循这些指南，以确保与 Hugo 正确构建。

新项目

新的 Docs 网站位于 gitlab-org/technical-writing/docs-gitlab-com 项目中。

发布后，原始 gitlab-org/gitlab-docs 项目中的所有问题都将转移到新项目，如果不再适用则关闭。

格式变更

页面标题

页面标题从 h1 标签移动到 title 前置属性。

例如，在 Nanoc 中，标题作为 h1 添加，如下所示：

---
stage: Systems
group: Cloud Connector
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.
---

# Cloud Connector: Configuration

A GitLab Rails instance accesses...

对于 Hugo，将标题移到页面的前置属性中：

---
stage: Systems
group: Cloud Connector
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: 'Cloud Connector: Configuration'
---

A GitLab Rails instance accesses...

原因：Hugo 可以生成页面的自动列表。要实现此功能，Hugo 需要将页面标题处理得更像数据而不是常规内容。我们最初不会使用这些功能，但将来可能会使用。

测试：错误级别的 Vale 规则 (FrontMatter.yml)。

短代码

自定义 Markdown 元素现在使用 Hugo 的短代码语法进行标记。

我们的自定义元素包括：

警告框
历史详情
功能可用性详情（tier、offering、status）
GitLab SVG 图标
标签

例如：

{{< alert type="warning" >}}

Don't delete your docs!

{{< /alert >}}

有关语法和示例，请参阅 Shortcodes 参考。

原因：短代码是创建自定义模板化内容块的标准 Hugo 方法。

测试：短代码在文档流水线中进行验证（参见实现问题）。

`/help` 中的短代码

短代码，就像我们现有的自定义 Markdown 元素一样，不会在 /help 中渲染。 /help 是 GitLab 自托管实例中内置的文档页面集（了解更多）。

短代码的语法更详细，因此我们已修改 /help 以隐藏这些标签，并为标签和警告框等元素显示简化的纯文本后备内容。

原因：/help 只渲染纯 Markdown。它不是具有转换内容或渲染模板化前端代码功能的静态站点生成器。

Kramdown

Kramdown 不再在网站上得到支持。

目前网站上存在的一些 Kramdown 标签示例：

{::options parse_block_html="true" /}

{: .alert .alert-warning}

使用 Hugo 后，这些标签将不再有任何效果。它们将作为纯文本渲染。

原因：Hugo 使用 Goldmark Markdown 渲染引擎，而不是 Kramdown。

测试：我们正在 CI 流水线中运行针对 Kramdown 标签的审计作业（示例）。这些标签将在发布过程中手动移除。

`navigation.yaml` 中的菜单项

我们简化了 navigation.yaml 文件的结构。现在有效的属性名称是 title、url 和 submenu，而不是在层次结构的每个级别使用不同的属性名称。

例如，Nanoc 网站的菜单数据如下所示：

sections:
- section_title: Tutorials
    section_url: 'ee/tutorials/'
    section_categories:
    - category_title: Find your way around GitLab
        category_url: 'ee/tutorials/gitlab_navigation.html'
        docs:
        - doc_title: 'Tutorial: Use the left sidebar to navigate GitLab'
            doc_url: 'ee/tutorials/left_sidebar/'

对于 Hugo，它看起来像这样：

- title: Tutorials
  url: 'tutorials/'
  submenu:
    - title: Find your way around GitLab
      url: 'tutorials/gitlab_navigation/'
      submenu:
        - title: 'Tutorial: Use the left sidebar to navigate GitLab'
          url: 'tutorials/left_sidebar/'

原因：在层次结构的每个级别使用相同的属性名称显著简化了我们对菜单进行编程操作的所有内容。它还简化了贡献者的菜单编辑。

作为 prettyURLs 更改的一部分，页面路径不应再包含 .html 扩展名。以尾部 / 结束每个 URL。

例如：

# Before
- category_title: Find your way around GitLab
  category_url: 'ee/tutorials/gitlab_navigation.html'

# After
- title: Find your way around GitLab
  url: 'tutorials/gitlab_navigation/'

测试：我们在此脚本中对 navigation.yaml 运行各种检查，该脚本在 YAML 文件更新时作为流水线作业运行。

文件命名

索引文件名

所有以前命名为 index.md 的文件都需要命名为 _index.md。例如：

Before:
doc/
├── user/
│   ├── index.md           # Must be renamed
│   └── feature/
│       └── index.md       # Must be renamed
└── admin/
    └── index.md           # Must be renamed

After:
doc/
├── user/
│   ├── _index.md         # Renamed
│   └── feature/
│       └── _index.md     # Renamed
└── admin/
    └── _index.md         # Renamed

原因：Hugo 要求目录索引页面（作为目录主页的页面）使用特定的命名约定。有关更多信息，请参阅 Hugo 关于 Page bundles 的文档。

测试：我们将在流水线中对此进行测试，并阻止包含 index.md 文件的合并（详细信息请参见此问题）。

文件名冲突

Hugo 配置为使用 PrettyURLs，它会从页面 URL 中删除 .html 扩展名。

当两个文件将在同一 URL 渲染时，会发生 路径冲突，使其中一个文件无法访问。

# Example 1
- doc/development/project_templates.md
- doc/development/project_templates/index.md
# Resulting URL for both: /development/project_templates/

# Example 2
- doc/user/gitlab_duo_chat.md
- doc/user/gitlab_duo_chat/index.md
# Resulting URL for both: /user/gitlab_duo_chat/

# Example 3
- doc/administration/dedicated/configure_instance.md
- doc/administration/dedicated/configure_instance/index.md
# Resulting URL for both: /administration/dedicated/configure_instance/

原因：Hugo 的 URL 路径选项是 prettyURLs 和 uglyURLs。这两者产生的路径与 Nanoc 网站有所不同。我们选择了 prettyURLs，因为它是 Hugo 的默认设置，而且 Hugo 的 uglyURLs 模式与其他大多数静态站点生成器不同。

测试：发布后，如果检测到新的路径冲突，Hugo 将在文档流水线中抛出错误。

流程

发布版本

发布版本不再需要更新 latest.Dockerfile。该文件不再存在于项目中，发布模板已相应更新。

原因：我们重构了版本控制，以使用并行部署功能。您可以在此处查看新的发布流程 here。

每月技术写作任务

Docs 项目维护任务轮换在我们使用 Hugo 发布时将暂停。

对于 2025 年 2 月，请在 2 月 12 日星期三之前运行损坏的外部链接和 start_remove 内容的检查。其他任务目前可以跳过。从 3 月开始，每月维护任务将暂停，直到另行通知。

这不会影响发布文章结构检查或每月文档发布任务。指定的技术作者应继续按原计划执行这些任务。

原因：一些 Ruby 脚本需要用 Go 重写，而且维护任务的优先级足够低，我们可以不它们就发布。发布后可能有更多机会将这些脚本与 Handbook 项目共享。

测试：由于我们将暂时暂停移除旧的重定向，我们添加了一个测试脚本来警告我们是否接近 Pages 重定向限制。

面向用户的变化

这些变化在我们发布新网站时生效。可以在 https://new.docs.gitlab.com 查看。

页面 URL

ee 前缀：我们从来自 GitLab 项目的页面路径中删除了 ee 前缀。该前缀是页面在 ce 和 ee 之间分割时的遗留产物，一直是网站访客困惑的来源。
优美的 URL：页面 URL 不再包含 .html 扩展名。位于 /foo/bar/baz.html 的文件可在 /foo/bar/baz 访问。

我们在 Cloudflare 设置了重定向，将所有 URL 重定向到它们的新格式。有关更多信息，请参阅 Hugo 项目中的重定向文档。

布局变化

我们实施了此问题中提出的布局更改，旨在提高可读性。

主要变化包括：

主内容列具有最大宽度。
主内容列（包括目录）在大屏幕上查看时居中，两侧有额外的空间。