• 查看项目 Wiki
• 为您的 Wiki 配置默认分支
• 创建 Wiki 主页
• 创建新的 Wiki 页面
  • 在本地创建或编辑 Wiki 页面
  • 页面标题中的特殊字符
  • 文件名和目录名的长度限制
• 编辑 Wiki 页面
  • 创建目录
• 删除 Wiki 页面
• 移动 Wiki 页面
• 导出 Wiki 页面
• 查看 Wiki 页面历史
  • 查看页面版本之间的更改
• 跟踪 Wiki 事件
• 自定义侧边栏
• 启用或禁用项目 Wiki
• 链接外部 Wiki
• 禁用项目 Wiki
• 富文本编辑器
  • 使用富文本编辑器
  • 切换回旧版编辑器
• 故障排除
  • 使用 Apache 反向代理的页面 slug 渲染
  • 使用 Rails 控制台重新创建项目 Wiki (BASIC SELF)

Wiki (BASIC ALL)

• 页面加载更改为异步于极狐GitLab 14.9。
• 页面 slug 编码方法更改为 ERB::Util.url_encode 于极狐GitLab 14.9。

如果您不想将文档保存在仓库中，但希望将其与代码保存在同一个项目中，您可以使用极狐GitLab 在每个极狐GitLab 项目中提供的 Wiki。每个 Wiki 都是一个单独的 Git 仓库，因此您可以在 Web 界面中创建 Wiki 页面，或者本地使用 Git。

极狐GitLab Wiki 支持 Markdown、RDoc、AsciiDoc 和 Org 的内容。用 Markdown 编写的 Wiki 页面支持所有 Markdown 功能，还提供一些对于链接的 Wiki 特定支持。

在 13.5 及更高版本中，Wiki 页面显示侧边栏，您可以自定义。此侧边栏包含 Wiki 中的部分页面列表，显示为嵌套树，同级页面按字母顺序列出。要查看所有页面的列表，请选择侧边栏中的 查看所有页面：

查看项目 Wiki

要访问项目 Wiki：

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

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

为您的 Wiki 配置默认分支

引入于 14.1 版本

Wiki 仓库的默认分支取决于您的极狐GitLab 版本：

• 14.1 及更高版本： Wiki 继承您的实例或群组配置的默认分支名称。如果没有配置自定义值，使用 main。
• 14.0 及更早版本： 使用 master。

对于任何版本，您可以为以前创建的 Wiki 重命名此默认分支。

创建 Wiki 主页

创建 Wiki 时是空的。在您第一次访问时，您可以创建用户在查看 Wiki 时看到的主页。此页面需要一个特定的标题才能用作您的 Wiki 主页。要创建它：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 在左侧边栏中，选择 计划 > Wiki。
3. 选择 创建您的第一个页面。
4. 系统要求第一页的标题为 home。具有此标题的页面用作您的 Wiki 的首页。
5. 选择 格式 来设置文本样式。
6. 在 内容 部分为您的主页添加欢迎信息。您以后可以随时对其进行编辑。
7. 添加 提交消息。Git 需要提交消息，因此如果您不自己输入，系统会创建一个。
8. 选择 创建页面。

创建新的 Wiki 页面

至少具有开发者角色的用户可以创建新的 Wiki 页面：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 在左侧边栏中，选择 计划 > Wiki。
3. 在此页面或任何其他维基页面上选择 新建页面。
4. 选择内容格式。
5. 为新页面添加标题。页面标题使用特殊字符作为子目录和格式，并有长度限制。
6. 向您的 Wiki 页面添加内容。
7. （可选）附加一个文件，系统将其存储在 Wiki 的 Git 仓库中。
8. 添加 提交消息。Git 需要提交消息，因此如果您不自己输入，极狐GitLab 会创建一个。
9. 选择 创建页面。

在本地创建或编辑 Wiki 页面

Wiki 是基于 Git 仓库的，因此您可以在本地克隆并像处理其他所有 Git 仓库一样进行编辑。要在本地克隆 Wiki 仓库，请从任何 Wiki 页面的右侧边栏中选择 克隆仓库，然后按照屏幕上的说明进行操作。

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

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

页面标题中的特殊字符

Wiki 页面作为文件存储在 Git 仓库中，因此某些字符具有特殊含义：

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

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

引入于 13.10 版本

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

• 245 字节用于页面标题（保留 10 字节用于文件扩展名）。
• 255 字节的目录名称。

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

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

编辑 Wiki 页面

您至少需要开发者角色来编辑 Wiki 页面：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 在左侧边栏中，选择 计划 > Wiki。
3. 转到您要编辑的页面，然后：
   • 使用 e Wiki 键盘快捷键。
   • 选择编辑图标 ()。
4. 编辑内容。
5. 选择 保存更改。

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

创建目录

要从 Wiki 页面的副标题生成目录，请使用 [[_TOC_]] 标签。

删除 Wiki 页面

您至少需要开发者角色才能删除 Wiki 页面：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 在左侧边栏中，选择 计划 > Wiki。
3. 前往您要删除的页面。
4. 选择编辑图标 ()。
5. 选择 删除页面。
6. 确认删除。

移动 Wiki 页面

您至少需要开发者角色才能移动 Wiki 页面：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 在左侧边栏中，选择 计划 > Wiki。
3. 转到您要移动的页面。
4. 选择编辑图标 ()。
5. 将新路径添加到 标题 字段。例如，如果您在 company 下有一个名为 about 的 Wiki 页面，并且您想将其移动到 Wiki 的根目录，请将 标题 从 about 更改为 /about。
6. 选择 保存更改。

导出 Wiki 页面

• 引入于极狐GitLab 16.3，功能标志为 print_wiki。默认禁用。
• 在 JihuLab.com 和私有化部署版本中启用于极狐GitLab 16.5。

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

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 选择 计划 > Wiki。
3. 进入您要导出的页面。
4. 选择垂直省略号 ()，然后选择 打印为 PDF。

这样就创建了 Wiki 页面的 PDF 版本。

查看 Wiki 页面历史

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

• 页面的修订（Git commit SHA）。
• 页面作者。
• 提交消息。
• 最后一次更新。
• 以前的修订，通过在页面版本 列中选择修订号。

要查看 Wiki 页面的更改：

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

查看页面版本之间的更改

引入于 13.2 版本

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

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 在左侧边栏中，选择 计划 > Wiki。
3. 前往您感兴趣的 Wiki 页面。
4. 选择 页面历史 以查看所有页面版本。

5. 在 变更 列中选择您感兴趣的版本的提交消息。

   

跟踪 Wiki 事件

• 引入于极狐GitLab 13.10.
• Git 事件引入于极狐GitLab 13.10.
• Git 事件的功能标志移除于极狐GitLab 13.5。

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

• 用户个人资料
• 动态页面，取决于 Wiki 的类型：
  • 群组动态
  • 项目动态

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

自定义侧边栏

引入于极狐GitLab 13.8, 选择 编辑侧边栏 可以自定义侧边栏。

您至少需要开发者角色来自定义 Wiki 导航侧边栏。这个过程会创建一个名为 _sidebar 的 Wiki 页面，它完全取代了默认的侧边栏导航：

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

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

### [Home](home)

- [Hello World](hello)
- [Foo](foo)
- [Bar](bar)

---

- [Sidebar](_sidebar)

启用或禁用项目 Wiki

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

私有化部署安装实例的管理员可以配置其它 Wiki 设置。

您可以从群组设置禁用群组 Wiki。

链接外部 Wiki

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

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
2. 在左侧边栏中，选择 设置 > 集成。
3. 选择 外部 Wiki。
4. 将 URL 添加到您的外部 Wiki。
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 但将其打开（蓝色）。

富文本编辑器

• 引入于 14.0 版本
• 在编辑体验之间切换功能引入于 14.7 版本，功能标志名为 wiki_switch_between_content_editor_raw_markdown。默认启用。
• 在编辑体验之间切换功能一般可用于 14.10 版本。移除功能标志 wiki_switch_between_content_editor_raw_markdown。
• 从内容编辑器重命名为富文本编辑器于极狐GitLab 16.2。

极狐GitLab 为 Wiki 中的极狐GitLab Flavored Markdown 提供了所见即所得的编辑体验。

支持包括：

• 文本格式选项，包括粗体、斜体、块引号、标题和内联代码。
• 无序、有序和清单的列表格式。
• 创建和编辑表格的结构。
• 使用语法高亮插入和格式化代码块。
• Mermaid、PlantUML 和 Kroki 图的实时预览（引入于 15.2 版本）。
• 创建和编辑 HTML 评论（引入于极狐GitLab 15.7）。

使用富文本编辑器

1. 创建一个新的 Wiki 页面，或编辑一个现有的页面。
2. 选择 Markdown 作为您的格式。
3. 在 内容 上方，选择 编辑富文本。
4. 使用内容编辑器中提供的各种格式选项自定义页面内容。
5. 为新页面选择 创建页面，或为现有页面选择 保存更改：

富文本编辑模式保持默认，直到您切换回编辑原始源。

切换回旧版编辑器

1. 如果您在内容编辑器中编辑页面，滚动到 内容。
2. 选择 编辑源。

故障排除

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

在 14.9 及更高版本中，页面 slug 现在使用 ERB::Util.url_encode 方法进行编码。 如果您使用 Apache 反向代理，您可以在 Apache 配置的 ProxyPass 行添加一个 nocanon 参数，以确保您的页面 slug 正确呈现。

使用 Rails 控制台重新创建项目 Wiki (BASIC SELF)

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

1. 启动 Rails 控制台会话。

2. 运行这些命令：

   # Enter your project's path
   p = Project.find_by_full_path('<username-or-group>/<project-name>')
   
   # This command deletes the wiki project from the filesystem.
   GitlabShellWorker.perform_in(0, :remove_repository, p.repository_storage, p.wiki.disk_path)
   
   # Refresh the wiki repository state.
   p.wiki.repository.expire_exists_cache
   

Wiki 中的所有数据都已清除，可以使用了。