极狐 GitLab Logo

Wiki

  • Tier: 基础版，专业版，旗舰版
  • Offering: JihuLab.com，私有化部署

极狐 GitLab 的 Wiki 提供项目和群组文档，以一种熟悉的格式呈现。Wiki 页面：

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

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

Wiki 页面显示一个侧边栏，您可以进行自定义。

查看项目 Wiki#

要访问项目 Wiki：

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

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

配置 Wiki 的默认分支#

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

创建 Wiki 首页#

History
    • 页面主题和路径的分离引入于极狐GitLab 17.2，使用名为 wiki_front_matter 和 wiki_front_matter_title 的功能标志。默认禁用。
    • 功能标志 wiki_front_matter 和 wiki_front_matter_title 在极狐GitLab 17.3 中被移除。

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

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

创建新 Wiki 页面#

History
    • 页面主题和路径的分离引入于极狐GitLab 17.2，使用名为 wiki_front_matter 和 wiki_front_matter_title 的功能标志。默认启用。
    • 在极狐GitLab 17.3 中，功能标志 wiki_front_matter 和 wiki_front_matter_title 被移除。

先决条件：

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

本地创建或编辑 Wiki 页面#

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

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

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

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

页面路径中的特殊字符#

History
    • 在极狐GitLab 16.7 中引入了基于 front matter 的标题，使用名为 wiki_front_matter 和 wiki_front_matter_title 的功能标志。默认禁用。
    • 在极狐GitLab 17.2 中，wiki_front_matter 和 wiki_front_matter_title 功能标志默认启用。
    • 在极狐GitLab 17.3 中，wiki_front_matter 和 wiki_front_matter_title 功能标志被移除。

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

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

为了解决这些限制，您还可以在页面内容之前的前置内容块中存储 Wiki 页面的标题。例如：

yaml
---
title: Page title
---

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

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

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

非 ASCII 字符占用超过一个字节。

虽然您仍然可以在本地创建超过这些限制的文件，但您的团队成员可能无法随后在本地检出 Wiki。

编辑 Wiki 页面#

先决条件：

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

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

创建目录#

History
    • wiki 侧边栏的表内容引入于极狐GitLab 17.2。

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

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

删除 Wiki 页面#

先决条件：

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

移动或重命名 Wiki 页面#

History
    • Wiki 页面移动或重命名的重定向功能在极狐GitLab 17.1 中引入，使用名为 wiki_redirection 的功能标志，默认启用。
    • 页面标题与路径分离功能在极狐GitLab 17.2 引入，使用名为 wiki_front_matter 和 wiki_front_matter_title 的功能标志，默认启用。
    • wiki_redirection、wiki_front_matter 和 wiki_front_matter_title 这三个功能标志在极狐GitLab 17.3 被移除。

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

先决条件：

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

导出 Wiki 页面#

History
    • 引入于极狐GitLab 16.3，使用名为 print_wiki 的功能标志。默认禁用。
    • 在极狐GitLab 16.5 中，在 JihuLab.com 和私有化部署上启用。
    • 在极狐GitLab 16.6 中，功能标志 print_wiki 被移除。

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

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

Wiki 页面的 PDF 文件已创建。

Wiki 页面模板#

History
    • 引入于极狐GitLab 16.10。

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

创建模板#

先决条件：

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

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

应用模板#

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

先决条件：

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

查看 Wiki 页面的历史记录#

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

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

要查看 Wiki 页面的更改：

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

查看页面版本之间的更改#

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

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

侧边栏#

History
    • 在侧边栏中通过主题搜索引入于极狐GitLab 17.1。
    • 侧边栏中 15 个条目的限制引入于极狐GitLab 17.2。

Wiki 页面显示一个侧边栏，其中包含 Wiki 中页面的列表，以嵌套树的形式显示，兄弟页面按字母顺序列出。

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

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

自定义侧边栏#

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

先决条件：

  • 您必须至少拥有开发者角色。

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

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

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

markdown
1### 主页
2
3- [Hello World](hello)
4- [Foo](foo)
5- [Bar](bar)
6
7---
8
9- [Sidebar](_sidebar)

启用或禁用项目 Wiki#

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

极狐 GitLab 私有化部署的管理员可以配置其他 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 的过程，但将其切换为打开（为蓝色）。

富文本编辑器#

History
    • 在极狐GitLab 16.2 中，内容编辑器重命名为富文本编辑器。

极狐 GitLab 提供了一个用于 Wiki 的极狐 GitLab 风味 Markdown 的富文本编辑体验。

支持包括：

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

使用富文本编辑器#

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

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

另请参阅：

极狐 GitLab 风味 Markdown 支持#

在富文本编辑器中支持所有极狐 GitLab 风味 Markdown 内容类型的工作正在进行中。

跟踪 Wiki 事件#

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

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

故障排除#

使用 Apache 反向代理渲染页面 Slug#

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

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

  • Tier: 基础版，专业版，旗舰版
  • Offering: 私有化部署

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

任何直接更改数据的命令如果未正确运行或在正确的条件下运行，可能会导致损坏。我们强烈建议在测试环境中运行它们，并准备好实例的备份以便在必要时恢复。

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

  1. 启动 Rails 控制台会话。

  2. 运行以下命令：

    ruby
    1# 输入您的项目路径
2p = Project.find_by_full_path('<username-or-group>/<project-name>')
3
4# 此命令从文件系统中删除 Wiki 项目。
5p.wiki.repository.remove
6
7# 刷新 Wiki 仓库状态。
8p.wiki.repository.expire_exists_cache

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

相关主题#