GitLab 文档中的重定向

当你移动、重命名或删除页面时，必须添加重定向。重定向减少了用户通过过时链接访问文档站点时遇到 404 错误的频率。

添加重定向以确保：

• 用户能看到新页面，并可以更新或删除他们的书签。

• 外部网站可以更新他们的链接，特别是那些有自动化检查重定向链接的网站。

• 文档站点的全局导航不会链接到缺失的页面。

  全局导航中的链接已经在 docs-gitlab-com 项目中测试过。

确保为任何移动、重命名或删除页面的合并请求分配一名技术写手。技术写手可以帮助解答任何问题，并审查您的更改。

重定向的类型

有两种类型重定向：

• 添加到文档文件本身的重定向，适用于在 GitLab 自托管实例的 /help 中查看文档的用户。例如， GitLab.com 上的 /help。这些必须在重命名或移动文档的同一个合并请求中添加。内部页面的重定向在三个月后过期，外部页面（以 https: 开头）的重定向在一年后过期。
• GitLab Pages 重定向，在重定向文件过期后自动添加。它们不能由贡献者手动添加，并在九个月后过期。指向外部网站的重定向不会被添加到 GitLab Pages 重定向中。

过期的重定向文件作为技术团队 月度任务 的一部分，会从文档项目中移除。

重定向到已存在的页面

要将页面重定向到同一仓库中的另一个页面：

1. 在要重定向到新位置的 Markdown 文件中：

   • 删除所有内容。

   • 添加以下内容：

     ---
     redirect_to: '../newpath/to/file/_index.md'
     remove_date: 'YYYY-MM-DD'
     ---
     
     <!-- markdownlint-disable -->
     
     此文档已移动到 [另一个位置](../newpath/to/file/_index.md)。
     
     <!-- 此重定向文件可以在 <YYYY-MM-DD> 后删除。 -->
     <!-- 指向同一项目中其他文档的重定向在三个月后过期。 -->
     <!-- 指向不同项目或站点文档的重定向（例如，链接不是相对路径且以 `https:` 开头）在一年后过期。 -->
     <!-- 删除前，请参阅：https://docs.gitlab.com/development/documentation/redirects -->

   • 将两处 ../newpath/to/file/index.md 替换为新文件路径。

   • 将两处 YYYY-MM-DD 替换为过期日期，如模板中所述。

2. 如果该页面有其他页面未使用的图片，请删除它们。

更新其他仓库中的链接

提交更改后，搜索并更新所有可能链接到旧文件的其他仓库：

1. 在 https://gitlab.com/gitlab-com/www-gitlab-com 中，搜索完整 URL：

   grep -r "docs.gitlab.com/path/to/file" .

2. 在 https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/tree/main/data 中， 搜索导航栏配置文件中的路径：

   grep -r "path/to/file" .

3. 在 所有文档项目 中，搜索文档和代码库中的链接。 搜索所有变体，包括完整 URL 和仅路径。例如，转到 gitlab 项目的根目录并运行：

   grep -r "docs.gitlab.com/path/to/file" .
   grep -r "path/to/file" .
   grep -r "path/to/file.md" .
   grep -r "path/to/file" .

   您可能需要尝试相对链接的变体，例如 ../path/to/file 或 ../file 来找到所有情况。

4. 在 https://gitlab.com/gitlab-org/customers-gitlab-com 中，搜索完整 URL：

   grep -r "docs.gitlab.com/path/to/file" .

移动文件位置

如果你想将文件从一个位置移动到另一个位置，不要直接移动它。 相反，你应该复制文件，并向旧文件添加重定向代码。

1. 创建新文件。
2. 将旧文件的内容复制到新文件中。
3. 在旧文件中，删除所有内容。
4. 在旧文件中，添加重定向代码，并遵循 重定向到已存在的页面 主题中的其余步骤。

使用代码添加重定向

如果你更喜欢使用脚本来创建重定向：

通过运行以下 Rake 任务，将重定向代码添加到旧文档文件中。第一个参数是旧文件的路径， 第二个参数是新文件的路径：

• 要重定向到同一项目中的页面，使用相对路径和 .md 扩展名。 旧路径和新路径都从同一位置开始。在以下示例中，两个路径都相对于 doc/：

  bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, doc/api/new_file.md]"

• 要重定向到不同项目或站点中的页面，使用完整 URL（带 https://）：

  bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]"

• 或者，你可以省略参数，系统会提示你输入值：

  bundle exec rake gitlab:docs:redirect

重定向在发布前创建的页面

如果你创建了一个新页面，然后在它于 18 号被添加到发布之前重命名了它：

不要遵循该程序，而是请求技术写手动将重定向添加到 redirects.yaml。

创建重定向的例外情况

在某些情况下，你可以跳过添加重定向，直接删除文件。该页面必须已经从导航中移除（或从未存在于导航中），并且以下条件之一必须为真：

• 该页面在同一版本中被添加和删除，因此从未包含在 GitLab 自托管版本中。
• 该页面不包含任何有价值的内容，例如占位符页面或使用率极低的页面。