參與 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 現有的文章 進行更新:
流覽至您想要在 「hololens」 資料夾中編輯的文章。
選取右上方的 [編輯] 按鈕(鉛筆圖示)。
這會自動分叉預設分支,main。
根據 Markdown 基本概念編輯文章的內容。
在每個文章頂端更新元資料:
- 標題:檢視發行項時出現在瀏覽器索引標籤中的頁面標題。 頁面標題用於 SEO 和編製索引,因此除非有必要,否則請勿變更標題(雖然在文件公開之前,這較不重要)。
- 描述:撰寫文章內容的簡短描述,以提升 SEO 和探索。
- 作者:如果您是頁面的主要擁有者,請在這裡新增 GitHub 別名。
- ms.author:如果您是頁面的主要擁有者,請在這裡新增您的Microsoft別名(您不需要 @microsoft.com,只是別名)。
- ms.date:如果您要將主要內容新增至頁面,請更新日期,但不適用於釐清、格式、文法或拼字等修正。
- 關鍵詞:關鍵詞有助於 SEO(搜尋引擎優化)。 新增關鍵詞,以逗號和空格分隔,這是您文章特有的,但在清單中最後一個關鍵詞後面沒有標點符號。 您不需要新增適用於所有發行項的全域關鍵詞,因為這些關鍵詞是在其他地方管理。
當您完成文章編輯後,請向下捲動並選取 [建議檔案變更]
。 在下一個頁面上,選取 [建立提取要求],將自動建立的分支合併至預設分支,main。
針對您要編輯的下一篇文章重複上述步驟。
如果您的變更將重新命名或刪除現有的發行項,請務必新增重新導向。 如此一來,任何有現有文章連結的人仍然會處於正確的位置。 重新導向是由存放庫根目錄中 .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 在檔案存放庫中建立新文章:
使用右上方的 Fork 按鈕,從 MicrosoftDocs/hololens 的預設分支 主要建立分叉。
在 [hololens] 資料夾中,選取右上方 [建立新檔案]。
建立發行項的頁面名稱(使用連字元而非空格,而不使用標點符號或單引號),並附加 “.md”
重要
請務必從 「hololens」 資料夾中建立新的發行項。 您可以在新的檔案名行中檢查 「hololens/」 來確認這一點。
在新頁面頂端,新增下列元數據區塊:
--- title: description: author: ms.author: ms.date: ms.topic: article keywords: ---
如 編輯現有文章中所述,填入相關的元數據欄位。
使用 Markdown 基本概念撰寫文章內容。
在文章底部新增
## See also
區段,其中包含其他相關文章的連結。完成時,選取 [[認可新檔案]。
選取 [新的提取要求,並將分支的 主要 分支合併至 MicrosoftDocs/hololens 主要(請確定箭號指向正確的目的地)。
下列資源將協助您瞭解如何使用 Markdown 語言編輯檔:
- 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」 資料夾,或確定您已在網頁瀏覽器中完成下列動作:
- 派生了 MicrosoftDocs/hololens 存放庫。
- 編輯分叉中的文章。
- 將您在文章中參考的影像上傳至分支中的 「hololens/images」 資料夾。
- 已建立 提取要求,將您的分支合併至 microsoftDocs/hololens main 分支。
若要瞭解如何設定您自己的分支存放庫,請遵循 建立新文章的指示。
透過網頁瀏覽器在 GitHub 中編輯時,您可以選取頁面頂端附近的 [Preview] 索引卷標,以在認可之前預覽您的工作。
注意
Microsoft Learn 上預覽您的變更僅適用於Microsoft員工。
Microsoft員工:當貢獻已合併至預設分支時,主要,您可以在 </hololens?branch=main>公開內容之前先檢閱內容。 使用左側數據列中的目錄來尋找您的文章。
不過,在瀏覽器中編輯是進行快速變更的最簡單方式,但有一些缺點:
- 您不會進行拼字檢查。
- 您不會取得其他文章的任何智慧連結(您必須手動輸入文章的檔名)。
- 上傳和參考影像可能會很麻煩。
如果您不想處理這些問題,請在參與時,使用像是 Visual Studio Code 等桌面用戶端,實用的擴充功能。
基於上述 所列的原因,您可能偏好使用桌面用戶端來編輯檔,而不是網頁瀏覽器。 我們建議使用 Visual Studio Code。
請遵循下列步驟來設定 Visual Studio Code 以使用此存放庫:
- 在網頁瀏覽器中:
- 為您的電腦安裝 Git。
- 安裝 Visual Studio Code。
- 如果您尚未這麼做,Fork MicrosoftDocs/hololens。
- 在分叉中,選取 [複製或下載 並複製 URL。
- 在 Visual Studio Code 中建立分支的本機複本:
- 從 [檢視] 功能表中,選取 [命令選擇區]。
- 輸入 “Git: Clone”。”
- 貼上您複製的 URL。
- 選擇在您的電腦上儲存複製品的位置。
- 選取快顯 開啟存放庫。
使用下列工作流程透過 Visual Studio Code 對文件進行變更:
注意
使用 Visual Studio Code 時,上述所有
請確定您複製的分叉與官方存放庫是最新的。
在網頁瀏覽器中,建立提取要求,以同步處理 MicrosoftDocs/hololens 預設分支中其他參與者的最新變更,主要,到您的分支(請確定箭號指向正確的目的地)。
在 Visual Studio Code 中,選取 [同步處理] 按鈕,將剛更新的分叉同步至本機複製。
使用 Visual Studio Code 在複製存放庫中建立或編輯文章。
視需要編輯一或多個文章(視需要將影像新增至 “images” 資料夾)。
在 Explorer中儲存 變更。
認可 原始檔控制 中的所有 變更(出現提示時寫入認可訊息)。
選取 [同步處理] 按鈕,將變更同步回原始來源(GitHub 上的分支)。
在網頁瀏覽器中,建立提取要求,將分叉中的新變更同步回 MicrosoftDocs/hololens 主要(請確定箭頭指向正確的目的地)。
編輯檔案時,下列 Visual Studio Code 延伸模組很有用:
Docs Markdown Extension for Visual Studio Code - 使用 Alt+M 來顯示 Microsoft Learn 撰寫選項的功能表,例如:
- 已上傳的搜尋和參考影像。
- 新增清單、資料表和註標等格式設定,例如
>[!NOTE]
。 - 搜尋和參考內部連結和書籤(頁面內特定區段的連結)。
- 格式化錯誤會反白顯示(將滑鼠停留在錯誤上方以深入瞭解)。
代碼拼字檢查程式 - 拼錯字組會加上底線;以滑鼠右鍵按兩下拼錯字組,以變更或將它儲存至字典。