如何使用 Visual Studio Code 來取代難用的 Azure Wikis 線上編輯器 | The Will Will Web

The Will Will Web

記載著 Will 在網路世界的學習心得與技術分享

如何使用 Visual Studio Code 來取代難用的 Azure Wikis 線上編輯器

我們經常在 Azure DevOps Services 的專案中撰寫 Wiki 文件,但是 Azure DevOps 的 Wikis 線上編輯器實在是太難用了,我覺得還是在 VSCode 撰寫 Markdown 來的方便許多。除此之外,因為 Azure Wikis 可以放附件上去,但也不是所有檔案類型都支援,所以偶爾會遇到無法上傳附件的狀況。還有,你可能想要取回已經刪除的文件,但是從線上似乎沒有方法可以查閱這些文件。今天我打算用這篇文章來解決上述所有問題!

我曾經在 如何建立與刪除 Azure DevOps 上面的 Project Wiki 文件庫 這篇文章提到 Azure DevOps 上面的 Wikis 有兩種類型:

  1. Project Wiki

    每個專案只能有一個 Project Wiki

  2. Code Wiki

    所有 Wiki 文件會跟著 Azure Repos 中的分支一起管理。

本篇文章將會以 Project Wiki 為主,也是我們最常用的 Azure Wikis 使用方式。

將 Azure Wikis 視為 Git 儲存庫

其實 Azure DevOps 上面的 Project Wiki 背後,其實就是一個隱藏版的 Git 儲存庫 (Repository),只是檯面上沒有講的很明白而已。

我以以下這個開源的 AntiXss for .NET Standard 2.0 專案為例,我將其專案建立了一個相對應的 Azure DevOps 專案,其 Wiki 文件在此:

https://dev.azure.com/willh/AntiXss/_wiki/wikis/AntiXss.wiki/24/Home

我們來比對一下 Azure WikisAzure Repos 的網址差異:

  • https://dev.azure.com/willh/AntiXss/_wiki/wikis/AntiXss.wiki
  • https://dev.azure.com/willh/AntiXss/_git/AntiXss

事實上,你只要把 Azure Wikis 的網址稍微改一下,把 _wiki/wikis 換成 _git 就可以取得 Azure Wikis 的 Git Repo 網址:

  • https://dev.azure.com/willh/AntiXss/_git/AntiXss.wiki

所以,你是可以將整個專案的 Project Wiki 文件庫透過 Git 複製回來,預設分支名稱為 wikiMasterwikiMain

git clone https://dev.azure.com/willh/AntiXss/_git/AntiXss.wiki
cd AntiXss.wiki
code .

如此一來,你就可以改用 Visual Studio Code 來編輯整份 Wiki 文件了。不僅如此,由於這其實是一份完整的 Git 儲存庫,因此你可以直接在本機查閱完整的版本歷史紀錄,包含已經刪除的文件,都可以非常輕易的從 git log 歷史紀錄中找回,相當不錯!👍

從本地撰寫 Azure Wikis 文件的注意事項

雖然說你可以直接取得完整的 Project Wiki 文件庫,但是 Azure DevOps 的 Wiki 文件庫有一定的命名規定,如果不符合規定的話,該文件將不會正確顯示在 Azure DevOps 的 Wiki 文件庫中。

以下是我個人的使用經驗與建議:

  1. 因為頁面標題等於檔案名稱,而檔案命名有許多限制,遇到無效字元該頁面就會被隱藏,因此:
    1. 盡量不要在 VSCode 新增頁面
    2. 盡量不要在 VSCode 修改頁面標題
  2. 由於 Azure DevOps 只認單一分支(wikiMasterwikiMain),多人共同編輯文件時要注意衝突問題,所以:
    1. 修改前請先 git pull --dry-run 查看有無新版本
    2. 推送變更前請先 git push --dry-run 看會不會衝突
    3. 如果遭遇衝突,先考慮放棄現有變更,否則會蓋掉其他人的版本
    4. 有任何變更就隨時隨地 Commit/Push,避免單一分支出現衝突的狀況
  3. 文件中所需附件請一律請放在根目錄下的 .attachments 目錄中
    1. 文件中的超連結請一律用 /.attachments/ 作為啟始路徑
  4. 在 Project Wikis 文件庫的目錄名稱就是子頁面名稱
    1. 例如 Devs.md 文件,同層目錄就會有個 Devs 資料夾,放在該資料夾的檔案就是 Devs.md 文件的「子頁面」
  5. 在 Project Wikis 文件庫的文件可以自由排序
    1. 每個資料夾下可以有個 .order 檔案可以決定文件排序,裡面要放頁面名稱
    2. 如果刪除 .order 檔案,所有文件排序就會回歸依字母順序排序
    3. 就算你刪除 .order 檔案,之後你在 Azure DevOps 拖曳文件順利就會自動產生

由於頁面標題等於檔案名稱,其檔案命名的限制如下:

  1. 檔名與路徑的長度總和不得超過 235 個字元
  2. 所有的頁面標題必須是唯一的 (Uniqueness)
  3. 檔案名稱不能包含以下字元
    1. 出現 Unicode 控制字元 (control characters) 或 代理字元組 (surrogate characters)
    2. 出現 /, \# 字元
    3. 出現以 . 開頭或結尾的檔名 (文件檔名通常都是 .md 結尾)
  4. 有些特殊字元可以出現在頁面上,只是要編碼過
    1. 符號 : 必須編碼為 %3A
    2. 符號 < 必須編碼為 %3C
    3. 符號 > 必須編碼為 %3E
    4. 符號 * 必須編碼為 %2A
    5. 符號 ? 必須編碼為 %3F
    6. 符號 | 必須編碼為 %7C
    7. 符號 - 必須編碼為 %2D
    8. 符號 " 必須編碼為 %22

針對每一個單一檔案大小也有以下限制:

  1. 所有檔案大小不得超過 18MB
  2. 如果是附件檔案不得超過 19MB

相關連結