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

Wiki

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Wiki 以熟悉的格式提供项目和组文档。 Wiki 页面可以：

  • 使用 Markdown、RDoc、AsciiDoc 或 Org 格式生成技术文档、指南和知识库。
  • 创建与 GitLab 项目和组直接集成的协作文档。
  • 将文档存储在 Git 仓库中，以便进行版本控制和协作。
  • 通过侧边栏自定义支持自定义导航和组织。
  • 将内容导出为 PDF 文件，以便离线访问和分享。
  • 将内容与代码库分开维护，同时保持它们在同一项目中。

每个 Wiki 都是一个独立的 Git 仓库。 你可以通过 GitLab 网页界面或 本地使用 Git 创建和编辑 Wiki 页面。 使用 Markdown 编写的 Wiki 页面支持所有 Markdown 功能 并提供 Wiki 特定行为 的链接。

Wiki 页面显示一个 侧边栏，你可以自定义它。

查看项目 Wiki

要访问项目 Wiki：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目。
  2. 要显示 Wiki，可以：
    • 在左侧边栏，选择 计划 > Wiki。
    • 在项目中的任何页面上，使用 g + w Wiki 键盘快捷键。

如果 计划 > Wiki 未列在你项目的左侧边栏中，则项目管理员 已 禁用它。

为你的 Wiki 配置默认分支

你的 Wiki 仓库从你的实例或组继承 默认分支名称。 如果没有配置自定义分支名称，GitLab 使用 main。 要重命名 Wiki 的默认分支，请参阅 更新仓库中的默认分支名称。

创建 Wiki 主页

创建 Wiki 时，它是空的。在首次访问时，你可以创建用户查看 Wiki 时看到的主页。 此页面需要使用特定路径作为你的 Wiki 主页。要创建它：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 选择 创建你的第一页。
  4. 可选。更改主页的 标题。
  5. GitLab 要求第一页的路径为 home。此路径上的页面 用作你的 Wiki 的首页。
  6. 选择一种 格式 来设置文本样式。
  7. 在 内容 部分为主页添加欢迎消息。你可以 随时稍后编辑它。
  8. 添加 提交消息。Git 需要提交消息，因此如果你没有自行输入，GitLab 会创建一个。
  9. 选择 创建页面。

创建新的 Wiki 页面

先决条件：

  • 你必须至少拥有 Developer 角色。
  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 选择 Wiki 操作 ( ellipsis_v )，然后在此页面或任何其他 Wiki 页面上选择 新建页面。
  4. 选择内容格式。
  5. 为你的新页面添加 标题。
  6. 可选。取消勾选 从标题生成页面路径 并更改页面的 路径。 页面路径使用 特殊字符 作为子目录和格式， 并有 长度限制。
  7. 可选。为你的 Wiki 页面添加内容。
  8. 可选。附加文件，GitLab 将其存储在 Wiki 的 Git 仓库中。
  9. 添加 提交消息。Git 需要提交消息，因此如果你没有自行输入，GitLab 会创建一个。
  10. 选择 创建页面。

本地创建或编辑 Wiki 页面

Wiki 基于 Git 仓库，因此你可以克隆它们并在本地编辑， 就像处理其他 Git 仓库一样。要在本地克隆 Wiki 仓库：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 选择 Wiki 操作 ( ellipsis_v )，然后 克隆仓库。
  4. 按照屏幕上的说明操作。

你在本地添加到 Wiki 的文件必须使用以下 支持的扩展名之一，具体取决于你希望使用的标记语言。 具有不支持扩展名的文件在推送到 GitLab 时不会显示：

  • Markdown 扩展名：.mdown、.mkd、.mkdn、.md、.markdown。
  • AsciiDoc 扩展名：.adoc、.ad、.asciidoc。
  • 其他标记扩展名：.textile、.rdoc、.org、.creole、.wiki、.mediawiki、.rst。

页面路径中的特殊字符

Wiki 页面作为文件存储在 Git 仓库中，默认情况下，页面的文件名也是其标题。 文件名中的某些字符具有特殊含义：

  • 存储页面时，空格会转换为连字符。
  • 显示页面时，连字符 (-) 会转换回空格。
  • 斜杠 (/) 用作路径分隔符，不能显示在标题中。如果你 创建包含 / 字符的标题的文件，GitLab 会创建构建该路径所需的所有子目录。 例如，标题为 docs/my-page 会创建一个路径为 /wikis/docs/my-page 的 Wiki 页面。

为了绕过这些限制，你也可以将 Wiki 页面的标题存储在 页面内容之前的 front matter 块中。例如：

---
title: 页面标题
---

文件和目录名称的长度限制

许多常见文件系统对文件和目录名称有 255 字节限制。 Git 和 GitLab 都支持超过这些限制的路径。但是，如果你的文件系统强制执行这些限制， 你无法检出包含超过此限制的文件名的 Wiki 的本地副本。为防止此问题， GitLab 网页界面和 API 强制执行这些限制：

  • 文件名 245 字节（为文件扩展名保留 10 字节）。
  • 目录名 255 字节。

非 ASCII 字符占用多个字节。

虽然你仍然可以创建本地超过这些限制的文件，但你的队友 之后可能无法检出 Wiki 的本地副本。

编辑 Wiki 页面

先决条件：

  • 你必须至少拥有 Developer 角色。
  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 转到你要编辑的页面，然后：
  4. 编辑内容。
  5. 选择 保存更改。

Wiki 页面的未保存更改会保存在本地浏览器存储中，以防止意外数据丢失。

创建目录

内容中带有标题的 Wiki 页面会自动在侧边栏中显示目录部分。

你也可以选择在页面本身上单独显示目录部分。 要从 Wiki 页面的子标题生成目录，使用 [[_TOC_]] 标签。 有关示例，请阅读 目录。

删除 Wiki 页面

先决条件：

  • 你必须至少拥有 Developer 角色。
  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 转到你要删除的页面。
  4. 选择 Wiki 操作 ( ellipsis_v )，然后 删除页面。
  5. 确认删除。

移动或重命名 Wiki 页面

在 GitLab 17.1 及更高版本中，当你移动或重命名页面时，会自动 从旧页面到新页面设置重定向。重定向列表存储在 Wiki 仓库中的 .gitlab/redirects.yml 文件中。

先决条件：

  • 你必须至少拥有 Developer 角色。
  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 转到你要移动或重命名的页面。
  4. 选择 编辑。
  5. 要移动页面，在 路径 字段中添加新路径。例如， 如果你在 Company 下有一个名为 About 的 Wiki 页面，并希望 将其移动到 Wiki 的根目录，将 路径 从 About 更改为 /About。
  6. 要重命名页面，更改 路径。
  7. 选择 保存更改。

导出 Wiki 页面

你可以将 Wiki 页面导出为 PDF 文件：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 转到你要导出的页面。
  4. 在右上角，选择 Wiki 操作 ( ellipsis_v )，然后选择 打印为 PDF。

将创建 Wiki 页面的 PDF。

在 Wiki 中使用 Draw.io 创建图表

通过 diagrams.net 集成，你可以在 Wiki 页面上创建和嵌入 SVG 图表！图表编辑器在纯文本编辑器和富文本编辑器中都可用。

在 GitLab.com 上，此集成对所有 SaaS 用户启用，不需要任何额外配置。

在 GitLab Self-Managed 上，你可以与免费的 diagrams.net 网站集成，或在离线环境中托管你自己的 diagrams.net 网站。

要设置集成，你必须：

  1. 选择与免费的 diagrams.net 网站集成或配置你的 diagrams.net 服务器。
  2. 启用集成。

完成集成后，diagrams.net 编辑器会使用你提供的 URL 打开。

Wiki 页面模板

你可以创建模板，用于创建新页面时使用，或应用于现有页面。 模板是存储在 Wiki 仓库中 templates/ 目录中的 Wiki 页面。

创建模板

先决条件：

  • 你必须至少拥有 Developer 角色。
  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 选择 Wiki 操作 ( ellipsis_v )，然后 模板。
  4. 选择 新建模板。
  5. 输入模板标题、格式和内容，就像创建常规 Wiki 页面一样。

特定格式的模板只能应用于相同格式的页面。 例如，Markdown 模板仅适用于 Markdown 页面。

应用模板

当你 创建 或 编辑 Wiki 页面时， 你可以应用模板。

先决条件：

  • 你必须已经 创建 至少一个模板。
  1. 在 内容 部分，选择 选择模板 下拉列表。
  2. 从列表中选择一个模板。如果页面已有一些内容，会显示警告 指示现有内容将被覆盖。
  3. 选择 应用模板。

查看 Wiki 页面历史记录

Wiki 页面随时间的变化记录在 Wiki 的 Git 仓库中。 历史页面显示：

  • 页面的修订版本。
  • 页面作者。
  • 提交消息。
  • 最后更新。
  • 通过在 页面版本 列中选择修订号查看以前的修订版本。

要查看 Wiki 页面的更改：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 转到你要查看历史的页面。
  4. 选择 Wiki 操作 ( ellipsis_v )，然后 页面历史。

查看页面版本之间的更改

你可以查看 Wiki 页面版本中的更改，类似于版本化差异文件视图：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 转到你感兴趣的 Wiki 页面。
  4. 选择 Wiki 操作 ( ellipsis_v )，然后 页面历史 以查看所有页面版本。
  5. 在你感兴趣的版本的 差异 列中选择提交消息。

侧边栏

Wiki 页面显示一个侧边栏，其中包含 Wiki 中页面的列表， 显示为嵌套树，同级页面按字母顺序列出。

你可以使用侧边栏中的搜索框按标题快速查找页面。

出于性能原因，侧边栏限制显示 5000 个条目。要 查看所有页面的列表，在侧边栏中选择 查看所有页面。

自定义侧边栏

你可以手动编辑侧边栏导航的内容。

先决条件：

  • 你必须至少拥有 Developer 角色。

此过程会创建一个名为 _sidebar 的 Wiki 页面，它完全 替换默认的侧边栏导航：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目或组。
  2. 选择 计划 > Wiki。
  3. 在页面右上角，选择 添加自定义侧边栏 ( settings )。
  4. 完成后，选择 保存更改。

一个使用 Markdown 格式的 _sidebar 示例：

### 主页

- [你好世界](hello)
- [Foo](foo)
- [Bar](bar)

---

- [侧边栏](_sidebar)

启用或禁用项目 Wiki

Wiki 在 GitLab 中默认启用。项目 管理员 可以按照 共享和权限 中的说明 启用或禁用项目 Wiki。

GitLab Self-Managed 的管理员可以 配置其他 Wiki 设置。

你可以从 组设置 中禁用组 Wiki。

链接外部 Wiki

要从项目的左侧边栏添加外部 Wiki 的链接：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目。
  2. 选择 设置 > 集成。
  3. 选择 外部 Wiki。
  4. 添加你的外部 Wiki 的 URL。
  5. 可选。选择 测试设置。
  6. 选择 保存更改。

现在你可以在项目的 左侧边栏看到 外部 Wiki 选项。

当你启用此集成时，外部 Wiki 的链接不会替换内部 Wiki 的链接。 要从侧边栏隐藏内部 Wiki，禁用项目的 Wiki。

要隐藏外部 Wiki 的链接：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目。
  2. 选择 设置 > 集成。
  3. 选择 外部 Wiki。
  4. 在 启用集成 下，清除 活动 复选框。
  5. 选择 保存更改。

禁用项目的 Wiki

要禁用项目的内部 Wiki：

  1. 在左侧边栏，选择 搜索或跳转 并找到你的项目。
  2. 选择 设置 > 常规。
  3. 展开 可见性、项目功能、权限。
  4. 向下滚动找到并关闭 Wiki 切换（灰色）。
  5. 选择 保存更改。

内部 Wiki 现在已禁用，用户和项目成员：

  • 无法从项目的侧边栏找到 Wiki 的链接。
  • 无法添加、删除或编辑 Wiki 页面。
  • 无法查看任何 Wiki 页面。

之前添加的 Wiki 页面会被保留，以防你 想要重新启用 Wiki。要重新启用它，重复禁用 Wiki 的过程 但将其切换为开启状态（蓝色）。

富文本编辑器

GitLab 在 Wiki 中为 GitLab 风格 Markdown 提供富文本编辑体验。

支持包括：

  • 格式化文本，包括使用粗体、斜体、块引用、标题和行内代码。
  • 格式化有序列表、无序列表和清单。
  • 创建和编辑表格结构。
  • 插入和格式化带有语法高亮的代码块。
  • 预览 Mermaid、PlantUML 和 Kroki 图表。

使用富文本编辑器

  1. 创建 新 Wiki 页面，或 编辑 现有页面。
  2. 选择 Markdown 作为你的格式。
  3. 在 内容 下，左下角，选择 切换到富文本编辑。
  4. 使用富文本编辑器中提供的各种格式选项自定义你的页面内容。
  5. 对于新页面选择 创建页面，对于现有页面选择 保存更改。

要切换回纯文本，选择 切换到纯文本编辑。

另请参阅：

GitLab 风格 Markdown 支持

在富文本编辑器中支持所有 GitLab 风格 Markdown 内容类型是一项正在进行的工作。 有关 CommonMark 和 GitLab 风格 Markdown 支持的持续开发状态，请阅读：

跟踪 Wiki 事件

GitLab 跟踪 Wiki 创建、删除和更新事件。这些事件显示在以下页面上：

Wiki 的提交不计入 仓库分析。

故障排除

使用 Apache 反向代理的页面 slug 渲染

页面 slug 使用 ERB::Util.url_encode 方法编码。 如果你使用 Apache 反向代理，你可以在 Apache 配置的 ProxyPass 行中添加 nocanon 参数，以确保你的页面 slug 正确渲染。

使用 Rails 控制台重新创建项目 Wiki

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

此操作会删除 Wiki 中的所有数据。

任何直接更改数据的命令如果运行不正确或在 不正确的条件下运行，可能会造成损害。我们强烈建议在测试环境中运行它们， 并准备好实例的备份以便恢复，以防万一。

要清除项目 Wiki 中的所有数据并将其重新创建为空白状态：

  1. 启动 Rails 控制台会话。

  2. 运行以下命令：

    # 输入你的项目路径
p = Project.find_by_full_path('<用户名或组>/<项目名称>')

# 此命令从文件系统中删除 Wiki 项目。
p.wiki.repository.remove

# 刷新 Wiki 仓库状态。
p.wiki.repository.expire_exists_cache

Wiki 中的所有数据已被清除，Wiki 已准备好使用。

相关主题