參與 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 員工,請在 Microsoft 開放原始碼入口網站上將您的 GitHub 帳戶連結到您的 Microsoft 別名。 加入 「Microsoft」「MicrosoftDocs」 組織。

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

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

編輯現有的文章

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

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

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

    編輯文章。

    這會自動將可處置分支分支分叉至預設分支 main

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

  4. 更新每個文章頂端的中繼資料:

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

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

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

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

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

若要將重新導向新增至 .openpublishing.redirect.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. 使用右上方的[分支] 按鈕,從 MicrosoftDocs/hololens 的預設分支main建立分支。

    分支預設分支,目前名為 「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) 。

如果您使用Visual Studio Code (請參閱下列) 編輯檔,Docs Markdown 擴充 Visual Studio Code功能也可讓您輕鬆地產生資料表。

新增影像

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

重要

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

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

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

預覽您的工作

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

注意

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

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

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

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

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

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

使用 Visual Studio Code

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

設定

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

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

編輯檔

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

注意

上述所有編輯建立文章的指導方針,以及上述編輯 Markdown 的基本概念也適用于使用Visual Studio Code。

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

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

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

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

      按一下 [同步處理] 按鈕影像。

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

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

    2. 總管中儲存變更。

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

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

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

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

      按一下 [同步處理] 按鈕。

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

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

實用的延伸模組

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

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

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