共用方式為


參與 HoloLens 檔

歡迎使用 HoloLens 檔! 您在此存放庫中建立或編輯的任何文章,都會公開顯示。

HoloLens 檔發佈至 Microsoft Learn,其使用 GitHub 類別的 Markdown 與 Markdig 功能。 您在此存放庫中編輯的內容會格式化為顯示在 /hololens的文體化頁面。

此頁面涵蓋參與和 Markdown 基本概念連結的基本步驟和指導方針。 感謝您的貢獻!

可用的存放庫

存放庫名稱 URL
HoloLens MicrosoftDocs/HoloLens
混合實境 MicrosoftDocs/mixed-reality
VR愛好者指南 MicrosoftDocs/mixed-reality/enthusiast-guide

開始之前

如果您還沒有帳戶,則必須 建立 GitHub 帳戶

注意

如果您是Microsoft員工,請將 GitHub 帳戶連結至 Microsoft 開放原始碼入口網站上Microsoft別名,。 加入 「Microsoft」「MicrosoftDocs」 組織。

設定 GitHub 帳戶時,我們也建議您採取下列安全性預防措施:

  • 為您的 GitHub 帳戶建立 強密碼。
  • 開啟 雙因素驗證
  • 修復碼儲存在安全的地方
  • 更新您的 公用設定檔設定。
    • 設定您的名稱,並考慮將 公用電子郵件 設定為 不要在顯示電子郵件位址。
    • 建議您上傳配置檔圖片,因為縮圖會顯示在您參與的 Microsoft Learn 文章中。
  • 如果您打算使用命令列,請考慮設定適用於 Windows 的 Git 認證管理員 。 如此一來,每次做出貢獻時,就不必輸入密碼。

發佈系統會系結至 GitHub,因此這些步驟很重要。 您將使用 GitHub 別名,將列為每個文章的作者或參與者。

編輯現有的文章

使用下列工作流程,在網頁瀏覽器中透過 GitHub 現有的文章 進行更新:

  1. 流覽至您想要在 「hololens」 資料夾中編輯的文章。

  2. 選取右上方的 [編輯] 按鈕(鉛筆圖示)。

    編輯文章。

    這會自動分叉預設分支,main

  3. 根據 Markdown 基本概念編輯文章的內容。

  4. 在每個文章頂端更新元資料:

    • 標題:檢視發行項時出現在瀏覽器索引標籤中的頁面標題。 頁面標題用於 SEO 和編製索引,因此除非有必要,否則請勿變更標題(雖然在文件公開之前,這較不重要)。
    • 描述:撰寫文章內容的簡短描述,以提升 SEO 和探索。
    • 作者:如果您是頁面的主要擁有者,請在這裡新增 GitHub 別名。
    • ms.author:如果您是頁面的主要擁有者,請在這裡新增您的Microsoft別名(您不需要 @microsoft.com,只是別名)。
    • ms.date:如果您要將主要內容新增至頁面,請更新日期,但不適用於釐清、格式、文法或拼字等修正。
    • 關鍵詞:關鍵詞有助於 SEO(搜尋引擎優化)。 新增關鍵詞,以逗號和空格分隔,這是您文章特有的,但在清單中最後一個關鍵詞後面沒有標點符號。 您不需要新增適用於所有發行項的全域關鍵詞,因為這些關鍵詞是在其他地方管理。
  5. 當您完成文章編輯後,請向下捲動並選取 [建議檔案變更]

  6. 在下一個頁面上,選取 [建立提取要求],將自動建立的分支合併至預設分支,main

  7. 針對您要編輯的下一篇文章重複上述步驟。

重新命名或刪除現有的發行項

如果您的變更將重新命名或刪除現有的發行項,請務必新增重新導向。 如此一來,任何有現有文章連結的人仍然會處於正確的位置。 重新導向是由存放庫根目錄中 .openpublishing.redirection.json 檔案所管理。

若要將重新導向新增至 .openpublishing.redirection.json,請將專案新增至 redirections 陣列:

{
    "redirections": [
        {
            "source_path": "hololens/old-article",
            "redirect_url": "/base-url/new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • source_path 是您正在移除之舊文章的相對存放庫路徑。 請確定路徑開頭為 docset (在此案例中為 hololens),並包含 .md 擴展名。

  • redirect_url 是舊文章到新文章的相對公用URL。 請確定此 URL 包含 .md,並以 /開頭,因為它指的是公用 URL,而不是存放庫路徑。 允許使用 #section 連結至新文章內的區段。 如有必要,您也可以在這裡使用另一個網站的絕對路徑。

  • redirect_document_id 指出您是否要保留上一個檔案的文件識別碼。 預設值為 false。 如果您想要保留重新導向發行項的 ms.documentid 屬性值,請使用 true。 如果您保留文件識別碼,頁面檢視和排名等數據將會傳送至目標文章。 如果重新導向主要是重新命名,而不是只涵蓋部分相同內容之不同文章的指標,請執行此動作。

如果您新增重新導向,請務必刪除舊檔案。

建立新文章

使用下列工作流程,網頁瀏覽器中透過 GitHub 在檔案存放庫中建立新文章

  1. 使用右上方的 Fork 按鈕,從 MicrosoftDocs/hololens 的預設分支 主要建立分叉。

    分支的預設分支,目前名為 「main」。。

  2. 在 [hololens] 資料夾中,選取右上方 [建立新檔案]

  3. 建立發行項的頁面名稱(使用連字元而非空格,而不使用標點符號或單引號),並附加 “.md”

    為新頁面命名。

    重要

    請務必從 「hololens」 資料夾中建立新的發行項。 您可以在新的檔案名行中檢查 「hololens/」 來確認這一點。

  4. 在新頁面頂端,新增下列元數據區塊:

    ---
    title:
    description:
    author:
    ms.author:
    ms.date:
    ms.topic: article
    keywords:
    ---
    
  5. 編輯現有文章中所述,填入相關的元數據欄位。

  6. 使用 Markdown 基本概念撰寫文章內容。

  7. 在文章底部新增 ## See also 區段,其中包含其他相關文章的連結。

  8. 完成時,選取 [[認可新檔案]

  9. 選取 [新的提取要求,並將分支的 主要 分支合併至 MicrosoftDocs/hololens 主要(請確定箭號指向正確的目的地)。

    從分支建立提取要求到 MicrosoftDocs/hololens。

Markdown 基本概念

下列資源將協助您瞭解如何使用 Markdown 語言編輯檔:

新增數據表

由於表格在 Microsoft Learn 上的樣式,因此它們不會有框線或自定義樣式,即使您嘗試內嵌 CSS 也一樣。 它似乎在短時間內運作,但最終平臺會將樣式從數據表中去除。 因此,請事先規劃,並讓您的數據表保持簡單。 以下是一個網站,可讓 Markdown 數據表變得簡單:[資料表產生器](https://www.tablesgenerator.com/markdown_tables)。

Docs Markdown 延伸模組 for Visual Studio Code,如果您使用 Visual Studio Code,也可以輕鬆地產生數據表(請參閱下方) 來編輯檔。

新增影像

您必須將影像上傳至存放庫中的 「hololens/images」 資料夾,然後在文章中適當地參考它們。 影像會自動以完整大小顯示,這表示大型影像會填滿文章的整個寬度。 建議您在上傳影像之前預先重設大小。 建議的寬度介於 600 到 700 像素之間,不過,如果是密集螢幕快照或螢幕快照的分數,則應該相應增加或縮小。

重要

您只能在合併之前,將影像上傳至分叉存放庫。 因此,如果您打算將影像新增至文章,您必須 使用Visual Studio Code,先將影像新增至分支的 「images」 資料夾,或確定您已在網頁瀏覽器中完成下列動作:

  1. 派生了 MicrosoftDocs/hololens 存放庫。
  2. 編輯分叉中的文章。
  3. 將您在文章中參考的影像上傳至分支中的 「hololens/images」 資料夾。
  4. 已建立 提取要求,將您的分支合併至 microsoftDocs/hololens main 分支。

若要瞭解如何設定您自己的分支存放庫,請遵循 建立新文章的指示

預覽您的工作

透過網頁瀏覽器在 GitHub 中編輯時,您可以選取頁面頂端附近的 [Preview] 索引卷標,以在認可之前預覽您的工作。

注意

Microsoft Learn 上預覽您的變更僅適用於Microsoft員工。

Microsoft員工:當貢獻已合併至預設分支時,主要,您可以在 </hololens?branch=main>公開內容之前先檢閱內容。 使用左側數據列中的目錄來尋找您的文章。

在瀏覽器中編輯與使用桌面用戶端進行編輯

不過,在瀏覽器中編輯是進行快速變更的最簡單方式,但有一些缺點:

  • 您不會進行拼字檢查。
  • 您不會取得其他文章的任何智慧連結(您必須手動輸入文章的檔名)。
  • 上傳和參考影像可能會很麻煩。

如果您不想處理這些問題,請在參與時,使用像是 Visual Studio Code 等桌面用戶端,實用的擴充功能

使用 Visual Studio Code

基於上述 所列的原因,您可能偏好使用桌面用戶端來編輯檔,而不是網頁瀏覽器。 我們建議使用 Visual Studio Code

設置

請遵循下列步驟來設定 Visual Studio Code 以使用此存放庫:

  1. 在網頁瀏覽器中:
    1. 為您的電腦安裝 Git
    2. 安裝 Visual Studio Code
    3. 如果您尚未這麼做,Fork MicrosoftDocs/hololens
    4. 在分叉中,選取 [複製或下載 並複製 URL。
  2. 在 Visual Studio Code 中建立分支的本機複本:
    1. 從 [檢視] 功能表中,選取 [命令選擇區]
    2. 輸入 “Git: Clone”。”
    3. 貼上您複製的 URL。
    4. 選擇在您的電腦上儲存複製品的位置。
    5. 選取快顯 開啟存放庫

編輯檔

使用下列工作流程透過 Visual Studio Code 對文件進行變更:

注意

使用 Visual Studio Code 時,上述所有 編輯建立 文章,以及編輯 Markdown的 基本概念。

  1. 請確定您複製的分叉與官方存放庫是最新的。

    1. 在網頁瀏覽器中,建立提取要求,以同步處理 MicrosoftDocs/hololens 預設分支中其他參與者的最新變更,主要,到您的分支(請確定箭號指向正確的目的地)。

      將 MicrosoftDocs/hololens 的變更同步處理至分支。

    2. 在 Visual Studio Code 中,選取 [同步處理] 按鈕,將剛更新的分叉同步至本機複製。

      按鍵按鍵影像。

  2. 使用 Visual Studio Code 在複製存放庫中建立或編輯文章。

    1. 視需要編輯一或多個文章(視需要將影像新增至 “images” 資料夾)。

    2. Explorer中儲存 變更。

      在總管中選擇 [全部儲存]

    3. 認可 原始檔控制 中的所有 變更(出現提示時寫入認可訊息)。

      在原始檔控制中選擇 [全部認可]

    4. 選取 [同步處理] 按鈕,將變更同步回原始來源(GitHub 上的分支)。

      按鍵按鍵。

  3. 在網頁瀏覽器中,建立提取要求,將分叉中的新變更同步回 MicrosoftDocs/hololens 主要(請確定箭頭指向正確的目的地)。

    從分支建立提取要求到 MicrosoftDocs/hololens。

有用的擴充功能

編輯檔案時,下列 Visual Studio Code 延伸模組很有用:

  • Docs Markdown Extension for Visual Studio Code - 使用 Alt+M 來顯示 Microsoft Learn 撰寫選項的功能表,例如:

    • 已上傳的搜尋和參考影像。
    • 新增清單、資料表和註標等格式設定,例如 >[!NOTE]
    • 搜尋和參考內部連結和書籤(頁面內特定區段的連結)。
    • 格式化錯誤會反白顯示(將滑鼠停留在錯誤上方以深入瞭解)。
  • 代碼拼字檢查程式 - 拼錯字組會加上底線;以滑鼠右鍵按兩下拼錯字組,以變更或將它儲存至字典。