将 Git 存储库发布到 Wiki

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

可以将已在 Git 存储库中维护的内容发布到 Wiki。 例如,此内容可以是软件开发工具包(SDK)支持、产品文档或自述文件。 还可以在单个团队项目中发布多个 Wiki。

将 Markdown 文件发布到 Wiki 时,将获得以下优势:

  • 将内容组织到分层页面结构中
  • 浏览和筛选目录
  • 发布新版本的内容
  • 以管理代码库的方式管理内容
  • 使用 Wiki 搜索功能轻松搜索 Wiki

有关详细信息,请参阅 “预配代码”和“发布代码”作为 wiki

提示

可以使用本文中的步骤添加和编辑发布到 Wiki 的内容。 还可以以通过 Git 存储库协作处理代码的方式脱机工作和更新 Wiki 内容。 有关详细信息,请参阅 脱机更新 Wiki 页面。

先决条件

  • 拥有团队项目。 如果没有项目, 请立即创建一 个项目。
  • 为项目启用 Azure Repos 服务。
  • 在团队项目中定义 Git 存储库。 理想情况下,此存储库至少包含一个要发布到 Wiki 的 Markdown 文件。 有关详细信息,请参阅 在项目中创建新的 Git 存储库。
  • 拥有将代码发布为 wiki 的权限 参与 。 默认情况下,为参与者组的成员设置此权限。 有权参与 Git 存储库的任何人都可以添加或编辑 Wiki 页面。

打开 Wiki

  1. 登录到组织(https://dev.azure.com/{yourorganization}),打开项目,然后选择“概述>Wiki”。

    显示 Wiki 选项卡选择的屏幕截图。

如果需要切换项目,请选择 Azure DevOps浏览所有项目。

将 Git 存储库发布到 Wiki

在现有 Git 存储库中维护 Markdown 文件并想要将其发布到 Wiki 时,请执行以下步骤。

  1. 选择“ 发布代码为 wiki”。

    显示突出显示的按钮的屏幕截图,其中“将代码发布为 wiki”。

    注意

    如果项目未定义 Git 存储库,则不会显示“发布代码作为 wiki”选项。 创建新的 Git 存储库,然后返回并刷新此页面。

  2. 如果已预配团队项目 Wiki,请选择“ 发布代码 Wiki”。

    显示“发布代码为 Wiki”菜单选项的屏幕截图。

  3. 选择包含 Markdown 文件的存储库、分支和文件夹,并输入 Wiki 存储库的名称。 Git 存储库必须位于团队项目中。

    显示 Wiki 存储库的输入名称的屏幕截图。

    如果要将存储库中的所有 Markdown 文件发布到 Wiki,请指定存储库的根目录。

  4. 选择发布。 Wiki 存储库使用所选存储库中包含的 Markdown 文件和文件夹填充。

    例如,下图显示了在步骤 2 中选择的 azure-docs-sdk-node 存储库中包含的文件的已发布存储库。

    现有存储库 Markdown 文件中已发布 Wiki 的屏幕截图。

    Wiki 目录(TOC)包含以下文件:

    • 存储库/分支/文件夹中定义的每个 Markdown 文件(文件类型= .md)按字母顺序列出,TOC 标题派生自 Markdown 文件名。

    • 已发布文件夹中定义的每个子文件夹的父页,即使它不包含任何 Markdown 文件也是如此。

      下图显示了 azure-docs-sdk-node 存储库的内容。

      发布到 Wiki 的 Markdown 文件的存储库的屏幕截图。

Git 存储库分支的负责人映射到 Wiki。 分支和所选文件夹内所做的任何更改都会自动反映在 Wiki 中。 没有涉及其他工作流。

注意

每个已发布的代码 Wiki 最多可以发布 10 个分支。

对于具有额外 Markdown 文件的预配 Wiki,可以添加或编辑页面的方式与在 Git 存储库中维护代码的方式相同。

编辑、重命名或删除页面

执行以下步骤以编辑、重命名或删除 Wiki 页面。

  1. 在项目中,打开 Repos>文件代码>文件。

  2. 选择所需的页面,选择“操作,然后选择该操作。

    Wiki 操作选项、编辑、重命名或删除的屏幕截图。

注意

通过在选择发布到 Wiki 的分支上定义分支策略,以管理任何其他 Git 存储库的方式管理 Wiki 存储库。 但是,如果没有定义任何策略,则可以进行更改,并从 Web 门户或客户端直接将其推送到分支。

编辑 页面

使用编辑模式下提供的链接预览更改,或突出显示以前版本所做的更改。 若要放弃更改,请选择“ 取消”。 有关支持的 Markdown 功能的详细信息,请参阅 Markdown 用法的语法指南。

  1. 完成后,添加有关更新的注释,然后选择“ 提交”。

    “提交”对话框的屏幕截图。

    系统会自动提供用于创建拉取请求的链接。 直接编辑 Wiki 分支时,可以忽略此消息。

    “创建拉取请求”链接的屏幕截图。

提示

更改文件的名称或大小写时,请更新 .order 该文件以反映更改。 有关详细信息,请参阅 更改页面序列,添加或更新 .order 文件

重命名页面

要在 TOC 中显示的所有页面都必须是文件类型 .md

  1. 选择“重命名以相应地重命名文件。

例如,在下图中,我们将 new-home-page.md 重命名New-Home-Page.md。 此页面显示在 TOC 中,标签为“新建主页”。

“重命名提交”对话框的屏幕截图。

页面标题区分大小写,并且必须在文件夹中是唯一的,并且长度为 235 个字符或更少。 有关其他游戏限制的详细信息,请参阅 页面标题命名限制

删除页面

可以从已发布文件夹中删除不希望显示在 Wiki 中的任何 Markdown 文件。 如果该文件包含在 .order 文件中,请从 .order 文件中删除其条目。 有关详细信息,请参阅 更改页面序列、添加或更新 .order 文件

添加页面或页面

可以将以下页面添加到已发布的 Wiki:

  • 从 Web 门户将文件添加到根文件夹或子文件夹
  • 将文件上传到根文件夹或子文件夹
  • 添加或更新 .order 文件以指定 Wiki TOC 中的页面序列

每次更新都需要将更改提交到存储库。 然后,可以刷新已发布存储库的 Wiki 来查看更改。

从 Web 门户添加页面

  1. 已发布存储库的 Repos>文件代码>文件中,选择“操作,然后选择“文件”。

    从 Web 门户将页面添加到 Wiki 的屏幕截图。

  2. 输入页面的名称,确保指定 .md 文件类型。 文件名应与要在 TOC 中显示的页面标题相对应,短划线代替空格。 指定不超过 235 个字符的唯一标题。 页面标题区分大小写。 有关其他游戏限制的详细信息,请参阅 页面标题命名限制

    例如,若要添加在 TOC 中显示为第 4 页的页面,请添加名为 Page-4.md 的文件。

    显示“创建”按钮的新文件对话框的屏幕截图。

  3. 输入页面的内容。 有关详细信息,请参阅 Markdown 文件的语法指南、小组件、wiki 和拉取请求注释

  4. 完成后,选择“ 提交”。

将文件上传到文件夹

  1. 如果已定义现有内容,则可以将其上传到文件夹。 选择“操作,然后选择“上传文件”。

    显示突出显示的选定内容“上传文件”的屏幕截图。

  2. 完成“提交”对话框窗体,选择要上传的文件夹和文件。

    显示用于上传文件的“提交”对话框的屏幕截图。

添加父页和子页

若要添加父页,请先在根文件夹级别添加 Markdown 文件,然后添加具有相同标签的文件夹。

  1. 若要添加文件夹,请选择“文件夹,然后完成“新建文件夹”对话框窗体。 指定至少一个文件以对应于文件夹中的子页。

    “创建文件夹”对话框的屏幕截图。

  2. 将想要作为子页的所有文件添加到文件夹。

添加或更新 .order 文件

将文件或文件夹添加到 Wiki 存储库的最后一步是添加或更新 .order 更新的文件夹的文件。 此操作反映要在 TOC 中显示的页面序列。 有关详细信息,请参阅 更改页面序列、添加或更新 .order 文件。 文件中未列出的 .order 任何文件都将被添加到字母列表的末尾,因为其顺序设置为 int.MaxValue

更改页面序列、添加或更新 .order 文件

每个 .order 文件定义文件夹中包含的页面序列。 根 .order 文件指定在根级别定义的页面序列。 对于每个文件夹, .order 文件定义添加到父页的子页序列。

  1. 可以添加文件的方式与从“代码>文件”页添加.order任何文件的方式相同。 为 .order 文件命名。

  2. 编辑文件的内容以反映文件夹中包含的 Markdown 文件序列。 每个条目都应镜像文件名,但没有 .md 文件类型。 标题区分大小写,因此条目应与文件名中使用的大小写匹配。

例如:

README
page-2
page-3
Page-4
Misc content

设置主页

默认情况下,按字母顺序显示在根目录中的第一个文件设置为 Wiki 主页。 在 Web 门户中选择 Wiki 时,将打开主页。

  1. 通过在根 .order 文件中设置页面序列来更改主页。

例如,在第一行中输入页面名称。

New home page name here
page-2
page-3
Page-4
README
Misc content

将文件夹提升到页面

若要使文件夹也是一个页面,需要一个与文件夹同名的 Markdown 文件,该文件设置为文件夹的同级文件。 因此,文件夹和 .md 同名文件应彼此相邻。

如以下示例所示,Test 具有一个文件夹和一个 .md 文件,用于在 Wiki 树中创建层次结构。

显示将文件夹提升到页面的屏幕截图。

选择 Wiki 版本

若要选择 Wiki 版本,请从 Wiki 页面的分支选项中选择版本。

显示 Wiki 下拉菜单中所选 Wiki 版本的屏幕截图。

取消发布代码 Wiki

如果不再需要将存储库发布为 Wiki,可以选择取消发布它。

警告

取消发布 Wiki 会取消发布整个代码 Wiki,其中包括之前发布的存储库的所有版本。

  1. 选择要取消发布的 Wiki,打开上下文菜单,然后选择“ 取消发布 Wiki”。

    取消发布 Wiki 确认对话框的屏幕截图。

  2. 通过选择 “取消发布”确认要取消发布 Wiki。

    未发布的 Wiki 的屏幕截图。