Git 中的Wiki檔案和資料夾結構

2025-05-30

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 分支上定義分支原則，以同樣的方式管理 Wiki 儲存庫，就像管理其他 Git 儲存庫。您也可以變更本機 wikiMain 分支，並將它們直接推送至遠端分支，而不需要定義任何原則。

Wiki 存放庫包含下列檔案和資料夾：

位於根層級之每個 Markdown 頁面的檔案
名為 .order 的檔案位於根層級，也位於每個子資料夾中
每個具有子頁面的維基頁面之子資料夾
名為 .attachments 的資料夾，用來儲存Wiki中使用的所有附件

檔案命名慣例

每個Wiki頁面的檔名會對應至Wiki頁面標題。在檔名中，連字元（-）代表頁面標題中的空格。例如，「如何參與」頁面標題會對應至檔名 How-to-contribute.md。 Wiki 頁面的 URL 路徑包含檔名。例如： https://github.com/ExampleWiki/How-To/How-to-contribute.md 。此方法可協助確保隨著維基變更，頁面的書籤連結保持不變。

每個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 會在網頁瀏覽器中顯示

Wiki 的 TOC 螢幕快照，其中已展開數個資料夾以顯示子資料夾。

.order 檔案會定義 TOC 頁面順序

Git 存放庫中Wiki資料夾和檔案清單的螢幕快照。.order 檔案已開啟，並顯示 TOC 頁面順序的定義。

.order 檔案會將順序從字母順序變更為 “Marketing”，後面接著 “Fabrikam Fiber”。

如需如何重新排序Wiki頁面的詳細資訊，請參閱新增、編輯和重新排序Wiki頁面。

還原字母順序

如果資料夾有自定義序列，您可以依照下列步驟，將排序方法還原為字母順序：

複製 wiki 的克隆 URL，並在瀏覽器中開啟該 URL。 Wiki 的 Git 存放庫隨即開啟。
前往您希望還原的 .order 檔案，然後刪除該檔案。刪除檔案之後，Git 會自動為該位置建立新的 .order 檔案。新檔案會使用預設序列。

共用方式為