通过

Git 中的 Wiki 文件和文件夹结构

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

本文描述了预配 Wiki 和作为代码发布的 Wiki 的文件和文件夹结构。 对于这两种类型的 Wiki，文件都存储在 Git 存储库中。 文件可以包括 Markdown 页面、代码、图像、附件或其他项目。 若要建立文件的呈现序列，Git 会在每个存储库文件夹中添加一个特殊文件（.order）。

创建项目时，默认情况下不会创建 Wiki。 你可以 预配 Wiki、 创建自述文件或 发布项目代码作为 Wiki。

使用 Azure DevOps 用户界面创建 Wiki。 然后，可以从 Git 存储库 URL 路径编辑 Wiki。

存储库文件和文件夹结构

Wiki 的 Git 存储库有两个命名约定：

  • Wiki 存储库的名称是<ProjectName>.wiki，其中<ProjectName>是你的项目名称。
  • Wiki 存储库的根分支的名称为 wikiMain。

你可以通过在 wikiMain 分支上定义分支策略，以管理其他 Git 存储库的方式来管理 Wiki 存储库。 还可以对本地 wikiMain 分支进行更改，并将其直接推送到远程分支，而无需定义任何策略。

Wiki 存储库包含以下文件和文件夹：

  • 位于根级别的每个 Markdown 页面对应的文件
  • 一个名为 .order 的文件位于根级别，也位于每个子文件夹中
  • 每个包含子页的 Wiki 页面的子文件夹
  • 一个名为 .attachments 的文件夹，用于存储 Wiki 中使用的所有附件

文件命名约定

每个 Wiki 页面的文件名对应于 Wiki 页面标题。 在文件名中，连字符 （-） 表示页面标题中的空格。 例如，页面标题“如何参与”对应于文件名 How-to-contribute.md。 Wiki 页面的 URL 路径包括文件名。 例如，https://github.com/ExampleWiki/How-To/How-to-contribute.md。 此方法有助于确保随着 Wiki 随时间的变化，指向页面的书签链接保持不变。

每个 Wiki 页面对应于 Wiki Git 存储库中的一个文件。 以下限制适用于页面文件名和文件大小：

  • 文件名：为页面文件选择名称时，请记住，文件的完全限定路径应为 235 个字符或更少。 页面的完整路径包括存储库 URL、页面文件的文件夹路径和页面文件名。 例如，https://github.com/ExampleWiki/Contributors/Code/How-to-add-code-to-the-project.md。

  • 唯一性：页面文件名在其 Wiki 存储库层次结构中的文件夹位置内必须是唯一的。 名称区分大小写。

  • 特殊字符：页面文件名对以下特殊字符有限制：

    • 无 Unicode 控制字符或代理字符
    • 无可打印字符：正斜杠、反斜杠/\、哈希#
    • 名称开头或结尾处没有句点 . 符号

  • 文件大小：最大页面文件大小为 18 MB。

  • 附件文件大小：页面文件的任何附件的最大大小为 19 MB。

允许的特殊字符

页文件名中允许使用多个特殊字符，例如冒号 : 和连字符 -。 例如，可以将 Markdown 文件命名为 FAQ：0525 或 Setup-Guide。

重要

若要避免页面语法和浏览器导航中的错误，请勿在页面文件名中使用空格字符（ ）。 如果基于页面标题命名页面文件，请将页面标题中的任何空格替换为文件名中的连字符（-）。

下表列出了 Wiki 页面文件名中允许的特殊字符和相应的 URI 编码字符串：

字符 符号 URI 字符串
结肠 : %3A
左尖括号 < %3C
右尖括号 > %3E
星号 （通配符） * %2A
问号 ? %3F
管道 | %7C
连字符 （短划线） - %2D
双引号 " %22

例如，文件名 FAQ：0525 编码为 FAQ%3A0525。

页面序列和 .order 文件

.order 文件定义 Wiki 页面序列。 Git 在每个文件夹中查找此文件，以标识要在该位置显示文件的序列。 默认页面序列按文件名按字母顺序（A 到 Z）。

定义自定义页面序列

当文件夹没有 .order 文件时，Git 使用默认的字母顺序。

可以通过更新文件夹中的 .order 文件（包括根级别）来定义任何文件夹的自定义序列。

以下视觉对象显示了 Wiki 目录（TOC）和创建 TOC 的相应 .order 文件的示例。

Wiki TOC 在 Web 浏览器中显示

Wiki 的 TOC 的屏幕截图，其中展开了多个文件夹以显示子文件夹。

.order 文件定义 TOC 页面序列

Git 存储库中 Wiki 文件夹和文件列表的屏幕截图。.order 文件处于打开状态，并显示 TOC 页面序列的定义。

.order 文件将序列从字母顺序更改为先“Marketing”，然后是“Fabrikam Fiber”。

有关如何对 Wiki 页面重新排序的详细信息，请参阅 添加、编辑和重新排序 Wiki 页面。

还原字母顺序

如果文件夹具有自定义序列，可以按照以下步骤将排序方法还原为字母顺序：

  1. 复制 Wiki 的克隆 URL，并在浏览器中打开它。 此时会打开 Wiki 的 Git 存储库。

  2. 前往您想还原并删除的 .order 文件。 删除文件后，Git 会自动为该位置创建新的 .order 文件。 新文件使用默认序列。

相关内容