將 Git 存放庫發佈至 Wiki

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

您可以將已在 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]。

    Screenshot showing selection of wiki tab.

如果您需要切換專案,請選取 [Azure DevOps ] 以 流覽所有專案

  1. 登入您的組織 (https://dev.azure.com/{yourorganization}) 並選取 [Wiki]。

將 Git 存放庫發佈至 Wiki

當您在現有的 Git 存放庫中維護 Markdown 檔案,並想要將它們發佈至 Wiki 時,請執行下列步驟。

  1. 選取 [ 將程式代碼發佈為Wiki]。

    Screenshot showing highlighted button, Publish code as wiki.

    注意

    如果您的專案未定義 Git 存放庫,[發佈程式代碼為wiki] 選項將不會顯示。 建立新的 Git 存放庫,然後傳回並重新整理此頁面。

  2. 如果您已佈建小組專案 Wiki,請選取 [ 發佈程式代碼 Wiki]。

    Screenshot showing Publish code as wiki menu option.

  3. 選擇包含 Markdown 檔案的存放庫、分支和資料夾,然後輸入 Wiki 存放庫的名稱。 Git 存放庫必須位於小組專案中。

    Screenshot showing entered name for the wiki repo.

    當您想要將存放庫中的所有 Markdown 檔案發佈至 Wiki 時,請指定存放庫的根目錄。

  4. 選取發行。 Wiki 存放庫會填入您所選取存放庫中所包含的 Markdown 檔案和資料夾。

    例如,下圖顯示您在步驟 2 中選取之 azure-docs-sdk-node 存放庫中所含檔案的已發佈存放庫。

    Screenshot of Published wiki from existing repo Markdown files.

    Wiki 目錄 (TOC) 包含下列檔案:

    • 儲存機制/分支/資料夾中定義的每個 Markdown 檔案 (檔案類型= .md) 都會依字母順序列出,TOC 標題衍生自 Markdown 檔名。

    • 已發行資料夾內定義之每個子資料夾的父頁面,即使它不包含任何 Markdown 檔案也一樣。

      下圖顯示 azure-docs-sdk-node 存放庫的內容。

      Screenshot of repo with Markdown files published to wiki.

Git 存放庫分支的負責人會對應至Wiki。 分支和所選資料夾內所做的任何變更都會自動反映在Wiki中。 沒有其他涉及的工作流程。

注意

每個已發佈的程式代碼 Wiki 最多可以發佈 10 個分支。

對於具有額外 Markdown 檔案的已佈建 Wiki,您可以使用在 Git 存放庫中維護程式代碼的方式新增或編輯頁面。

編輯、重新命名或刪除頁面

請執行下列步驟來編輯、重新命名或刪除Wiki頁面。

  1. 在您的專案中,開啟 Repos> 檔案程式碼>檔案。

  2. 選擇您想要的頁面,選取 [ 動作],然後選擇作業。

    Screenshot of wiki action options, Edit, rename, or delete.

注意

在選取發佈至Wiki的分支上定義分支原則,以相同方式管理您的Wiki存放庫。 但是,若未定義任何原則,您可以進行變更,並從入口網站或用戶端直接推送至分支。

編輯 頁面

使用編輯模式中可用的連結來預覽您的變更,或醒目提示從舊版所做的變更。 若要捨棄您的變更,請選取 [ 取消]。 如需所支援 Markdown 功能的詳細資訊,請參閱 Markdown 使用方式的語法指引。

  1. 完成時,請新增有關更新的批注,然後選取 [ 認可]。

    Screenshot of the Commit dialog.

    系統會自動提供您建立提取要求的連結。 當您直接編輯Wiki分支時,可以忽略此訊息。

    Screenshot of Create a pull request link.

提示

當您變更檔案的名稱或大小寫時,請更新 .order 檔案以反映變更。 如需詳細資訊,請參閱 變更頁面順序、新增或更新 .order 檔案

重新命名頁面

您要出現在 TOC 中的所有頁面都必須是檔案類型 .md

  1. 選取 [重新命名 ] 以據以重新命名檔案。

例如,在下圖中,我們會將 new-home-page.md 重新命名New-Home-Page.md。 此頁面會出現在 TOC 中,其標籤為「新增首頁」。

Screenshot of the Rename Commit dialog.

頁面標題會區分大小寫,且在資料夾內必須是唯一的,且必須少於 235 個字元。 如需其他標題限制的詳細資訊,請參閱 頁面標題命名限制

刪除頁面

您可以從已發佈的資料夾刪除任何不想出現在 Wiki 中的 Markdown 檔案。 如果您將檔案包含在檔案中 .order ,請從 .order 檔案中刪除其專案。 如需詳細資訊,請參閱 變更頁面順序、新增或更新 .order 檔案

新增頁面或頁面

您可以將下列頁面新增至已發布的 Wiki:

  • 從入口網站將檔案新增至根資料夾或子資料夾
  • 將檔案上傳至根資料夾或子資料夾
  • 新增或更新 .order 檔案,以指定Wiki TOC中的頁面順序

每個更新都需要您將變更認可至存放庫。 然後,您可以重新整理已發行存放庫的Wiki,以檢閱變更。

從入口網站新增頁面

  1. 已發佈存放庫的存放庫>檔案程式碼>檔案中,選取 [動作],然後選擇 [檔案]。

    Screenshot of adding a page to the wiki from the web portal.

  2. 輸入頁面的名稱,請務必指定 .md 文件類型。 檔名應該會對應至您想要出現在 TOC 中的頁面標題,其中虛線會取代空格。 指定 235 個字元或更少的唯一標題。 頁面標題會區分大小寫。 如需其他標題限制的詳細資訊,請參閱 頁面標題命名限制

    例如,若要新增在 TOC 中顯示為第 4 頁的頁面,請新增名為 Page-4.md的檔案。

    Screenshot showing new file dialog with Create button.

  3. 輸入頁面的內容。 如需詳細資訊,請參閱 Markdown 檔案、小工具、Wiki 和提取要求批註的語法指引。

  4. 完成時,請選取 [ 認可]。

將檔案上傳至資料夾

  1. 如果您已定義現有的內容,您可以將它上傳至資料夾。 選取 [動作],然後選擇 [上傳檔案]。

    Screenshot showing highlighted selection, Upload files.

  2. 完成 [ 認可 ] 對話框窗體,選取您要上傳的資料夾和檔案。

    Screenshot showing the Commit dialog for uploading files.

新增父頁面和子頁面

若要新增父頁面,請先在根資料夾層級新增 Markdown 檔案,然後新增具有相同標籤的資料夾。

  1. 若要新增資料夾,請選取 [資料夾],然後完成 [ 新增資料夾] 對話框表單。 指定至少一個檔案,以對應至資料夾中的子頁面。

    Screenshot of the Create folder dialog.

  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首頁。 當您在入口網站中選取 Wiki 時,首頁隨即開啟。

  1. 設定根 .order 檔案中的頁面順序,以變更首頁。

例如,在第一行中輸入頁面名稱。

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

將資料夾升階為頁面

若要讓資料夾成為頁面,您需要與資料夾同名的 Markdown 檔案,並設定為資料夾的同層級。 因此,資料夾和 .md 相同名稱的檔案應該彼此相鄰。

如下列範例所示,Test 同時具有資料夾和 .md 檔案,它會在Wiki樹狀結構中建立階層。

Screenshot showing Promotion of a folder to a page.

選取Wiki版本

若要選取 Wiki 版本,請從 Wiki 頁面的分支選項中選擇版本。

Screenshot showing a selected wiki version from the wiki dropdown menu.

解除發佈程式代碼Wiki

如果您不想再將存放庫發佈為Wiki,您可以選擇將它解除發佈。

警告

解除發佈Wiki會取消發佈整個程式碼Wiki,其中包含您先前發佈的存放庫所有版本。

  1. 選取您要取消發佈的Wiki、開啟操作功能表,然後選取 [取消發佈Wiki]。

    Screenshot of Unpublish a wiki confirmation dialog.

  2. 選擇 [取消發佈],確認您想要取消發佈Wiki。

    Screenshot of unpublishing wiki.