极狐 GitLab

维基

Tier: 基础版，专业版，旗舰版

Offering: JihuLab.com，私有化部署

维基以熟悉的格式提供项目和群组文档。 维基页面：

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

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

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

查看项目维基#

要访问项目维基：

  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目。
  2. 要显示维基，请执行以下任一操作：
    • 在左侧边栏中，选择 计划 > 维基 。
    • 在项目中的任何页面，使用 g+w 维基键盘快捷键 。

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

为你的维基配置默认分支#

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

创建维基首页#

版本历史
  • 页面标题和路径的分离在极狐GitLab 17.2 中 引入，并带有名为 wiki_front_matter 和 wiki_front_matter_title 的 功能标志。默认启用。
  • 功能标志 wiki_front_matter 和 wiki_front_matter_title 在极狐GitLab 17.3 中移除。

当创建维基时，它是空的。在第一次访问时，你可以创建用户在查看维基时看到的首页。此页面需要一个特定的路径才能用作你的维基首页。要创建它：

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

创建新的维基页面#

版本历史
  • 页面标题和路径的分离在极狐GitLab 17.2 中 引入，并带有名为 wiki_front_matter 和 wiki_front_matter_title 的 功能标志。默认启用。
  • 功能标志 wiki_front_matter 和 wiki_front_matter_title 在极狐GitLab 17.3 中移除。
  • 从顶部栏创建维基页面在极狐GitLab 18.10 中 引入。

先决条件：

  • 具有开发者、维护者或所有者角色。

从项目或群组创建新的维基页面：

  1. 在顶部栏上，选择 搜索或跳转到 并找到你的群组或项目。
  2. 在右上角，选择 新建 （），然后选择 新建维基页面 。

或者：

  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 选择 维基操作 （），然后在此页面或任何其他维基页面上选择 新建页面 。

打开新页面表单后，完成以下步骤：

  1. 选择一个内容格式。
  2. 为你的新页面添加一个 标题 。
  3. 可选。取消选中 从标题生成页面路径 并更改页面的 路径 。 页面路径使用 特殊字符 作为子目录和格式， 并且有 长度限制 。
  4. 可选。向你的维基页面添加内容。
  5. 可选。附加一个文件，极狐GitLab 将其存储在维基的 Git 仓库中。
  6. 添加一条 提交消息 。Git 需要一条提交消息，因此如果你没有自己输入，极狐GitLab 会创建一条。
  7. 选择 创建页面 。

从模板#

版本历史
  • 直接从模板创建新维基页面在极狐GitLab 18.6 中 引入。

如果你在项目中至少有一个模板，则可以从 模板 创建新的维基页面。

先决条件：

  • 你必须已经 创建 了至少一个模板。
  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 选择 模板 查看所有可用的模板。
  4. 在你想要使用的模板旁边，选择 从模板创建 。
  5. 新页面表单将打开，其中：
    • 模板内容预先填充在内容区域中。
    • 在模板下拉列表中选定了该模板。
  6. 输入你新页面的标题。
  7. 根据需要修改内容。
  8. 选择 创建页面 。

在本地创建或编辑维基页面#

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

  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 选择 维基操作 （），然后选择 克隆仓库 。
  4. 按照屏幕上的说明操作。

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

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

页面路径中的特殊字符#

版本历史
  • 在极狐GitLab 16.7 中 引入 了基于前文的标题，并带有名为 wiki_front_matter 和 wiki_front_matter_title 的 功能标志。默认禁用。
  • 功能标志 wiki_front_matter 和 wiki_front_matter_title 在极狐GitLab 17.2 中默认启用。
  • 功能标志 wiki_front_matter 和 wiki_front_matter_title 在极狐GitLab 17.3 中移除。

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

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

为了规避这些限制，你还可以将维基页面的标题存储在页面内容之前的前文块中。例如：

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

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

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

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

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

虽然你仍然可以在本地创建超出这些限制的文件，但之后你的团队可能无法在本地检出该维基。

编辑维基页面#

版本历史
  • 在极狐GitLab 18.11 中，预览模式下 引入 了粘性 编辑 按钮。

先决条件：

  • 你必须具有开发者、维护者或所有者角色。
  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 转到你要编辑的页面，然后执行以下任一操作：
  4. 编辑内容。
  5. 选择 保存更改 。

当你预览页面并滚动时，页面顶部的粘性栏会保持 编辑 按钮和其他操作可访问。

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

创建目录#

版本历史
  • 极狐GitLab 17.2 中在维基侧边栏中 引入 了目录。

内容中包含标题的维基页面会在侧边栏中自动显示目录部分。

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

删除维基页面#

先决条件：

  • 你必须具有开发者、维护者或所有者角色。
  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 转到你要删除的页面。
  4. 选择 维基操作 （），然后选择 删除页面 。
  5. 确认删除。

移动或重命名维基页面#

版本历史
  • 针对移动或重命名的维基页面的重定向在极狐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 及更高版本中，当你移动或重命名页面时，会自动设置从旧页面到新页面的重定向。重定向列表存储在维基仓库中的 .gitlab/redirects.yml 文件中。

先决条件：

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

导出维基页面#

版本历史

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

  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 转到你要导出的页面。
  4. 在右上角，选择 维基操作 （），然后选择 打印为 PDF 。

将创建该维基页面的 PDF 文件。

在维基中使用 Draw.io 创建图表#

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

在 JihuLab.com 上，此集成对所有用户启用，无需任何额外配置。

在私有化部署实例上，你可以与免费的 diagrams.net 网站集成，或在离线环境中托管你自己的 diagrams.net 站点。

要设置集成，你必须：

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

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

维基页面模板#

版本历史
  • 在极狐GitLab 16.10 中 引入。

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

创建模板#

先决条件：

  • 你必须具有开发者、维护者或所有者角色。
  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 选择 维基操作 （），然后选择 模板 。
  4. 选择 新建模板 。
  5. 输入模板标题、格式和内容，就像创建常规维基页面一样。

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

应用模板#

当你正在 创建 或 编辑 维基页面时， 你可以应用模板。

先决条件：

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

将页面模板恢复到以前的版本#

版本历史
  • 在极狐GitLab 18.6 中 引入。

你可以从其历史记录中将维基页面模板恢复到任何以前的版本。 这会创建一个具有恢复内容的新版本，同时保留完整的版本历史记录。

先决条件：

  • 你必须具有开发者、维护者或所有者角色。

将维基页面模板恢复到以前的版本：

  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 选择 维基操作 （），然后选择 模板 。
  4. 选择一个模板。
  5. 选择 维基操作 （），然后选择 模板历史记录 。
  6. 选择你要恢复的版本。
  7. 在右上角，选择 恢复此版本 。
  8. 在提交对话框中，添加一条 提交消息 来描述你恢复此版本的原因。
  9. 选择 恢复 。

页面模板将恢复到所选版本。所有以前的版本都保留在页面历史记录中。

你还可以使用相同的过程 恢复维基页面。

维基页面订阅#

维基页面订阅功能允许你在收到你感兴趣的维基页面发生更改时通知。 此功能可以让团队成员了解重要文档的更新，从而增强协作。

你可以订阅特定的维基页面，以便在有人执行以下操作时接收通知：

  • 向页面添加评论
  • 回复评论

订阅维基页面#

  1. 打开你要关注的维基页面。
  2. 在右上角，编辑 旁边，选择铃铛图标 （）。
  3. 再次选择铃铛图标 （） 取消订阅。

当你更改订阅状态时，极狐GitLab 会显示一条确认消息：

  • 如果已订阅，通知已开启
  • 如果已取消订阅，通知已关闭

订阅权限#

任何有权查看维基页面的用户都可以订阅它。你的订阅状态是个人的，不会影响其他用户。

通知设置#

通知遵循你的项目通知设置。它们通过你配置的通知渠道传递。

查看维基页面的历史记录#

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

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

查看维基页面的更改：

  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 转到你要查看历史记录的页面。
  4. 选择 维基操作 （），然后选择 页面历史记录 。

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

你可以看到维基页面某个版本中所做的更改，类似于版本差异文件视图：

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

将维基页面恢复到以前的版本#

版本历史
  • 在极狐GitLab 18.6 中 引入。

你可以从其历史记录中将维基页面恢复到任何以前的版本。 这会创建一个具有恢复内容的新版本，同时保留完整的版本历史记录。

先决条件：

  • 你必须具有开发者、维护者或所有者角色。

将维基页面恢复到以前的版本：

  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 转到你要恢复的页面。
  4. 选择 维基操作 （），然后选择 页面历史记录 。
  5. 选择你要恢复的版本。
  6. 在右上角，选择 恢复此版本 。
  7. 在提交对话框中，添加一条 提交消息 来描述你恢复此版本的原因。
  8. 选择 恢复 。

页面将恢复到所选版本。所有以前的版本都保留在页面历史记录中。

你还可以使用相同的过程 恢复维基页面模板。

侧边栏#

版本历史
  • 在侧边栏中按标题搜索在极狐GitLab 17.1 中 引入。
  • 侧边栏中的 15 个项目限制在极狐GitLab 17.2 中 移除。
  • 侧边栏在极狐GitLab 18.6 中从页面右上角 移动到 左上角。
  • 浮动侧边栏切换在极狐GitLab 18.9 中 引入，并带有一个名为 wiki_floating_sidebar_toggle 的功能标志。默认禁用。
  • 浮动侧边栏切换在极狐GitLab 18.11 中 GA。功能标志 wiki_floating_sidebar_toggle 已移除。

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

你可以使用侧边栏中的搜索框按标题查找维基中的页面。你可以使用 位于页面左上角的侧边栏切换按钮 （

） 打开或关闭侧边栏。

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

自定义侧边栏#

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

先决条件：

  • 你必须具有开发者、维护者或所有者角色。

此过程会创建一个名为 _sidebar 的维基页面，该页面完全取代默认的侧边栏导航：

  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目或群组。
  2. 在左侧边栏中，选择 计划 > 维基 。
  3. 在页面的左上角，选择 添加自定义侧边栏 （）。
  4. 完成后，选择 保存更改 。

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

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

启用或禁用项目维基#

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

私有化部署实例的管理员可以 配置额外的维基设置。

你可以从 群组设置 禁用群组维基。

链接外部维基#

从项目的左侧边栏添加指向外部维基的链接：

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

现在，你可以从项目的左侧边栏中看到 外部维基 选项。

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

要隐藏指向外部维基的链接：

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

禁用项目的维基#

要禁用项目的内部维基：

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

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

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

之前添加的 wiki 页面会被保留，以备你 想要重新启用 wiki。要重新启用，请重复禁用 wiki 的过程，但将切换开关打开（蓝色）。

富文本编辑器#

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

极狐GitLab 为 wiki 中的极狐GitLab Flavored Markdown 提供了富文本编辑体验。

支持包括：

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

使用富文本编辑器#

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

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

另请参阅：

极狐GitLab Flavored Markdown 支持#

在富文本编辑器中支持所有极狐GitLab Flavored Markdown 内容类型的工作正在进行中。 有关 CommonMark 和极狐GitLab Flavored 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 已准备好使用。