將 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]。

   

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

將 Git 存放庫發佈至 Wiki

瀏覽器

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

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

   

   注意

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

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

   

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

   

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

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

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

   

   Wiki 目錄 （TOC） 包含下列檔案：

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

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

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

     

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

注意

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

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

Azure DevOps CLI

您可以使用 az devops wiki create 命令，將 Git 存放庫發佈至 Wiki。 若要開始使用，請參閱 開始使用 Azure DevOps CLI。 當您在現有的 Git 存放庫中維護 Markdown 檔案，並想要將它們發佈至 Wiki 時，請執行此命令。

注意

如果您的專案尚未定義 Git 存放庫，則無法將程式代碼發佈為wiki。 如有必要， 請建立新的 Git 存放庫，然後返回此頁面。

az devops wiki create [--mapped-path]
                      [--name]
                      [--org]
                      [--project]
                      [--repository]
                      [--type {codewiki, projectwiki}]
                      [--version]

參數

• mapped-path：型別 codewiki 的必要專案。 新Wiki的對應路徑。 例如，您可以指定 '/' 從存放庫的根目錄發佈。
• name：新Wiki的名稱。
• org：Azure DevOps 組織 URL。 您可以使用 命令來設定預設組織 az devops configure -d organization=ORG_URL。 如果未設定為預設值，或使用 命令進行挑選， git config 則為必要專案。 例如： --org https://dev.azure.com/MyOrganizationName/ 。
• project：項目的名稱或識別碼。 您可以使用 命令來設定預設專案 az devops configure -d project=NAME_OR_ID 。 如果未設定為預設值，或使用 命令進行挑選， git config 則為必要專案。
• repository：型別 codewiki 的必要專案。 要從中發佈Wiki之存放庫的名稱或標識碼。
• type：要建立的Wiki類型。 接受的值是 projectwiki （預設值） 和 codewiki。
• version：型別 codewiki 的必要專案。 要從中發佈程式代碼Wiki的存放庫分支名稱。

範例

下列命令會 codewiki 建立從 MyRepo 存放庫發佈的名為 「My New Wiki」。。 wiki 會發佈在 wikis 分支的 main 資料夾中，結果會以數據表格式顯示。

az devops wiki create --name "My New Wiki" --type codewiki --repository MyRepo --mapped-path /wikis --version main --output table

ID                                    Name         Type
------------------------------------  -----------  --------
77abd847-31ec-45e9-8622-a190df8e5917  My New Wiki  codewiki

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

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

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

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

   

注意

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

編輯 頁面

使用編輯模式中可用的連結來預覽您的變更，或醒目提示從舊版所做的變更。 若要捨棄您的變更，請選取 [ 取消]。 如需所支援 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：

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

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

從入口網站新增頁面

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

   

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首頁。 當您在入口網站中選取 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，其中包含您先前發佈的存放庫所有版本。

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

   

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

   

相關文章

• 遵循Wiki頁面並取得通知
• 已布建與已發佈的Wiki
• 離線更新Wiki
• Wiki Markdown 指導