• 查看项目Wiki
• 为您的Wiki配置默认分支
• 创建Wiki主页
• 创建新的Wiki页面
  • 在本地创建或编辑Wiki页面
  • 页面路径中的特殊字符
  • 文件名和目录名的长度限制
• 编辑Wiki页面
  • 创建目录
• 删除Wiki页面
• 移动或充命名Wiki页面
• 导出Wiki页面
• Wiki页面模板
  • 创建模板
  • 应用模板
• 查看Wiki页面历史
  • 查看页面版本之间的更改
• 侧边栏
  • 自定义侧边栏
• 启用或禁用项目Wiki
• 链接外部Wiki
• 禁用项目Wiki
• 富文本编辑器
  • 使用富文本编辑器
  • GitLab风格的Markdown支持
• 跟踪Wiki事件
• 排查故障
  • 使用Apache反向代理时的页面Slug渲染
  • 使用Rails控制台重建项目Wiki （FREE ALL）
• 相关主题

Wiki

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

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

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

查看项目Wiki

要访问项目Wiki：

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

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

为您的Wiki配置默认分支

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

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

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

创建Wiki主页

• 在极狐GitLab 17.2中引入页面标题和路径分离标志，分别命名为wiki_front_matter和`wiki_front_matter_title，默认启用。
• 在极狐GitLab 17.3中移除特性标志wiki_front_matter和wiki_front_matter_title。

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

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

创建新的Wiki页面

• 在极狐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。

页面路径中的特殊字符

• 在极狐GitLab 16.7中引入基于前置信息的标题，通过标志 wiki_front_matter 和 wiki_front_matter_title，默认禁用。
• 在极狐GitLab 17.2中，标志 wiki_front_matterwiki_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 页面标题存储在页面内容之前的前置信息块中。例如：

---
title: Page title
---

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

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

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

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

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

编辑Wiki页面

先决条件： - 您至少需要开发者角色。

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

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

创建目录

在极狐GitLab 17.2中引入了左侧边栏中查看目录（Table of Contents，简称 TOC）。

具有标题的 Wiki 页面会自动在侧边栏显示一个目录部分。

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

删除Wiki页面

先决条件： - 您至少需要开发者角色。

1. 在左侧边栏，选择 搜索或转到，然后找到您的项目或组。
2. 选择 计划 > Wiki。
3. 转到您想删除的页面。
4. 选择 Wiki 操作 ()，然后选择 删除页面。
5. 确认删除。

移动或充命名Wiki页面

• 在极狐GitLab 17.1及更高版本中引入已移动或重命名的Wiki页面的重定向功能，并通过标志 wiki_redirection启用，默认启用。
• 在极狐GitLab 17.2中引入了页面标题和路径分离，并通过标志 wiki_front_matter 和 wiki_front_matter_title启用，默认启用。
• 在极狐GitLab 17.3中移除了标志 wiki_redirection、wiki_front_matter 和 wiki_front_matter_title。

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

先决条件：

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

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

导出Wiki页面

• 在极狐GitLab 16.3中引入，通过标志 print_wiki启用，默认禁用。
• 在极狐GitLab 16.5中引入极狐 saas和 自管理上启用。
• 在极狐GitLab 16.6中移除了功能标志 print_wiki。

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

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

系统将创建该 Wiki 页面的 PDF 文件。

Wiki页面模板

• 在极狐GitLab16.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. 选择 Diff 列中的提交信息，以查看您感兴趣的版本。

侧边栏

• 在极狐GitLab 17.1中引入了侧边栏中的按标题搜索功能。
• 在极狐GitLab 17.2中引入了侧边栏最多显示15项的限制。

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

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

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

自定义侧边栏

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

先决条件：

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

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

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

以下是一个_sidebar示例，使用Markdown格式： ```markdown ### Home

• Hello World
• Foo
• Bar

• Sidebar ```

启用或禁用项目Wiki

Wiki默认在极狐GitLab中启用。项目管理员可以按照共享和权限中的说明启用或禁用项目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，请重复禁用 Wiki 的过程，但将其切换为开启（蓝色）。

富文本编辑器

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

极狐GitLab中提供了用于GitLab风格的Markdown的富文本编辑体验。

支持的功能包括：

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

使用富文本编辑器

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

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

另见：

• 富文本编辑器

GitLab风格的Markdown支持

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

• 基本的 Markdown 格式扩展 史诗。
• GitLab 风格的 Markdown 扩展 史诗。

跟踪Wiki事件

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

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

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

排查故障

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

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

使用Rails控制台重建项目Wiki （FREE ALL）

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

警告： 任何直接更改数据的命令如果未正确执行，或者在不合适的条件下执行，可能会造成损害。我们强烈建议在测试环境中执行这些操作，并确保备份实例已准备好以便恢复，以防万一。

要清除项目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.
   p.wiki.repository.remove
      
   # Refresh the wiki repository state.
   p.wiki.repository.expire_exists_cache
   

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

相关主题

• 管理员 Wiki 设置
• 项目 Wiki API
• 组 Wiki API
• 组仓库存储迁移 API
• Wiki 键盘快捷键
• GitLab 风格的 Markdown
• Asciidoc