參與混合現實開發人員檔Contributing to Mixed Reality developer documentation

歡迎使用 適用于混合現實開發人員檔的公用存放庫!Welcome to the public repo for Mixed Reality developer documentation! 您在此存放庫中建立或編輯 的任何文章都將可在公用中看到。Any articles you create or edit in this repo will be visible to the public.

Mixed Reality 檔現在位於 docs.microsoft.com 平臺上,其使用具有 Markdig 功能的 GitHub flavored Markdown。The Mixed Reality docs are now on the docs.microsoft.com platform, which uses GitHub-flavored Markdown with Markdig features. 您在此存放庫中編輯的內容會格式化為顯示在上的樣式頁面 https://docs.microsoft.com/windows/mixed-realityThe content you edit in this repo gets formatted into stylized pages that show up at https://docs.microsoft.com/windows/mixed-reality.

本頁面涵蓋參與和連結至 Markdown 基本概念的基本步驟和指導方針。This page covers the basic steps and guidelines for contributing and links to Markdown basics. 感謝您的參與!Thank you for your contribution!

可用的存放庫Available repos

儲存機制名稱Repository name URLURL
混合實境Mixed Reality MicrosoftDocs/mixed-事實MicrosoftDocs/mixed-reality
VR 愛好者指南VR Enthusiasts Guide MicrosoftDocs/mixed-現實/愛好者指南MicrosoftDocs/mixed-reality/enthusiast-guide
HoloLensHoloLens MicrosoftDocs/HoloLensMicrosoftDocs/HoloLens

在您開始使用 Intune 之前Before you start

如果您還沒有帳戶,則必須 建立一個 GitHub 帳戶If you don't already have one, you'll need to create a GitHub account.

注意

如果您是 Microsoft 員工,請將您的 GitHub 帳戶連結到 Microsoft 開放原始碼入口網站上的 microsoft 別名。If you're a Microsoft employee, link your GitHub account to your Microsoft alias on the Microsoft Open Source portal. 加入「 Microsoft 」和「 MicrosoftDocs 」組織。Join the "Microsoft" and "MicrosoftDocs" organizations.

設定您的 GitHub 帳戶時,我們也建議這些安全性預防措施:When setting up your GitHub account, we also recommend these security precautions:

發佈系統系結至 GitHub,因此這些步驟非常重要。The publishing system is tied to GitHub, so these steps are important. 您將會使用您的 GitHub 別名,列為每篇文章的作者或參與者。You'll be listed as either author or contributor to each article using your GitHub alias.

編輯現有文章Editing an existing article

使用下列工作流程,在網頁瀏覽器中透過 GitHub 更新 現有文章Use the following workflow to make updates to an existing article via GitHub in a web browser:

  1. 流覽至您想要在「混合式事實檔」資料夾中編輯的文章。Navigate to the article you wish to edit in the "mixed-reality-docs" folder.

  2. 選取右上方的 [編輯] 按鈕 (鉛筆圖示) ,它會自動將可處置分支從 ' master ' 分支中分叉。Select the edit button (pencil icon) in the top right, which will automatically fork a disposable branch off the 'master' branch.

    編輯文章。

  3. 根據「 Markdown 基本概念」編輯文章的內容。Edit the content of the article according to the "Markdown basics".

  4. 更新每篇文章頂端的中繼資料:Update metadata at the top of each article:

    • 標題:在瀏覽器索引標籤中看到的頁面標題。title: Page title that appears in the browser tab when the article is being viewed. 頁面標題適用于 SEO 和索引編制,因此除非必要,否則請不要變更標題 (但在檔變成公用) 之前,這一點較不重要。Page titles are used for SEO and indexing, so don't change the title unless necessary (though this is less critical before documentation goes public).
    • 描述:撰寫文章內容的簡短描述,以提升 SEO 和探索。description: Write a brief description of the article's content, which boosts SEO and discovery.
    • 作者:如果您是頁面的主要擁有者,請在此新增您的 GitHub 別名。author: If you're the primary owner of the page, add your GitHub alias here.
    • ms. 作者:如果您是頁面的主要擁有者,請在這裡新增您的 Microsoft 別名, (您不需要 @microsoft.com 的別名) 。ms.author: If you're the primary owner of the page, add your Microsoft alias here (you don't need @microsoft.com, just the alias).
    • ms. 日期:如果您要將主要內容新增至頁面,請更新日期,而不是針對像是澄清、格式化、文法或拼寫的修正。ms.date: Update the date if you're adding major content to the page, but not for fixes like clarification, formatting, grammar, or spelling.
    • 關鍵字:關鍵字有助於 SEO (搜尋引擎優化) 。keywords: Keywords aid in SEO (search engine optimization). 新增您的文章所特有的關鍵字(以逗號和空格分隔),但在清單中的最後一個關鍵字之後不會有任何標點符號。Add keywords, separated by a comma and a space, that are specific to your article, but no punctuation after the last keyword in your list. 您不需要新增套用至所有文章的全域關鍵字,因為這些都是在其他地方管理。You don't need to add global keywords that apply to all articles, as those are managed elsewhere.
  5. 當您完成文章編輯之後,請向下滾動並選取 [ 建議檔案變更]。When you've completed your article edits, scroll down and select Propose file change.

  6. 在下一個頁面上,選取 [ 建立提取要求 ],將自動建立的分支合併至 [master]。On the next page, select Create pull request to merge your automatically created branch into 'master.'

  7. 針對您要編輯的下一篇文章重複上述步驟。Repeat the steps above for the next article you want to edit.

重新命名或刪除現有文章Renaming or deleting an existing article

如果您的變更將重新命名或刪除現有的文章,請務必新增重新導向。If your change will rename or delete an existing article, be sure to add a redirect. 如此一來,任何人只要有現有文章的連結,就都能在正確的位置結束。That way, anyone with a link to the existing article will still end up in the right place. 重新導向是由存放庫根目錄中的 .openpublishing.redirection.json 檔案來管理。Redirects are managed by the .openpublishing.redirection.json file in the root of the repo.

若要將重新導向新增至 .openpublishing.redirection.js,請將專案新增至 redirections 陣列:To add a redirect to .openpublishing.redirection.json, add an entry to the redirections array:

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • source_path是您即將移除之舊發行項的相對存放庫路徑。The source_path is the relative repository path to the old article that you're removing. 請確定路徑的開頭為 mixed-reality-docs 且結尾為 .mdBe sure the path starts with mixed-reality-docs and ends with .md.
  • redirect_url是舊發行項到新文章的相對公用 URL。The redirect_url is the relative public URL from the old article to the new article. 請確定此 URL 包含 mixed-reality-docs.md ,因為它參考的是公用 URL,而不是存放庫路徑。Be sure that this URL doesn't contain mixed-reality-docs or .md, as it refers to the public URL and not the repository path. 允許使用連結至新文章內的區段 #sectionLinking to a section within the new article using #section is allowed. 如有必要,您也可以在此處使用其他網站的絕對路徑。You can also use an absolute path to another site here, if necessary.
  • redirect_document_id 指出您是否要保留先前檔案中的檔識別碼。redirect_document_id indicates whether you would like to keep the document ID from the previous file. 預設為 falseThe default is false. true如果您想要保留重新導向之發行項的屬性值,請使用 ms.documentidUse true if you want to preserve the ms.documentid attribute value from the redirected article. 如果您保留檔識別碼,資料(例如頁面流覽和排名)將會傳送至目標文章。If you preserve the document ID, data, such as page views and rankings, will be transferred to the target article. 如果重新導向主要是重新命名,而不是僅涵蓋部分相同內容之不同文章的指標,請這麼做。Do this if the redirect is primarily a rename, and not a pointer to different article that only covers some of the same content.

如果您新增重新導向,也請務必刪除舊的檔案。If you add a redirect, be sure to delete the old file as well.

建立新文章Creating a new article

使用下列工作流程,在網頁瀏覽器中透過 GitHub 建立檔儲存機制中的 新文章Use the following workflow to create new articles in the documentation repo via GitHub in a web browser:

  1. 使用右上方的 [ 分叉 ] 按鈕) ,在 MicrosoftDocs/mixed 事實 ' master ' 分支 (建立分支。Create a fork off the MicrosoftDocs/mixed-reality 'master' branch (using the Fork button in the top right).

    分叉 master 分支。

  2. 在 [mixed---檔] 資料夾中,選取右上方的 [ 建立新 檔案]。In the "mixed-reality-docs" folder, select Create new file in the top right.

  3. 建立發行項的頁面名稱 (使用連字號,而不是空格,而且不使用標點符號或單引號) 並附加 "md"Create a page name for the article (use hyphens instead of spaces and don't use punctuation or apostrophes) and append ".md"

    命名您的新頁面。

    重要

    請確定您是從「混合式事實-檔」資料夾內建立新的文章。Make sure you create the new article from within the "mixed-reality-docs" folder. 您可以在新的檔案名行中檢查 "/mixed-reality-docs/" 來確認這一點。You can confirm this by checking for "/mixed-reality-docs/" in the new file name line.

  4. 在新頁面的頂端,加入下列中繼資料區塊:At the top of your new page, add the following metadata block:

    ---
    title:
    description:
    author:
    ms.author:
    ms.date:
    ms.topic: article
    keywords:
    ---
    
  5. 根據 上一節中的指示,填寫相關的元資料欄位。Fill in the relevant metadata fields per the instructions in the section above.

  6. 使用 Markdown 基本概念來撰寫文章內容。Write article content using Markdown basics.

  7. ## See also 文章底部新增一個區段,並提供其他相關文章的連結。Add a ## See also section at the bottom of the article with links to other relevant articles.

  8. 完成時,選取 [ 認可新 檔案]。When finished, select Commit new file.

  9. 選取 [ 新增提取要求 ],並將分叉的「主要」分支合併至 MicrosoftDocs/mixed 事實 ' master ' (確定箭號指向) 的正確方式。Select New pull request and merge your fork's 'master' branch into MicrosoftDocs/mixed-reality 'master' (make sure the arrow is pointing the correct way).

    從您的分支建立提取要求至 MicrosoftDocs/mixed-事實

Markdown 基本概念Markdown basics

下列資源將協助您瞭解如何使用 Markdown 語言來編輯檔:The following resources will help you learn how to edit documentation using the Markdown language:

加入資料表Adding tables

由於 docs.microsoft.com 樣式表的方式,即使您嘗試內嵌 CSS,它們也不會有框線或自訂樣式。Because of the way docs.microsoft.com styles tables, they won’t have borders or custom styles, even if you try inline CSS. 這項作業會在一小段時間內正常運作,但最終平臺會從資料表中去除樣式。It will appear to work for a short period of time, but eventually the platform will strip the styling out of the table. 所以事先規劃,讓您的資料表保持簡單明瞭。So plan ahead and keep your tables simple. 以下是讓 Markdown 資料表更簡單的網站Here’s a site that makes Markdown tables easy.

如果您使用 Visual Studio Code, 適用于 Visual Studio Code 的檔 Markdown 延伸 模組也可讓您輕鬆地產生資料表, (請參閱下方) 以編輯檔。The Docs Markdown Extension for Visual Studio Code also makes table generation easy if you're using Visual Studio Code (see below) to edit the documentation.

新增影像Adding images

您必須將映射上傳至存放庫中的「混合式事實-檔/映射」資料夾,然後在文章中適當地參考它們。You’ll need to upload your images to the "mixed-reality-docs/images" folder in the repo, and then reference them appropriately in the article. 影像會自動以完整大小顯示,這表示大型影像將會填滿整篇文章的寬度。Images will automatically show up at full-size, which means large images will fill the entire width of the article. 建議您先預先調整映射大小,然後再上傳。We recommend pre-sizing your images before uploading them. 建議的寬度介於600到700圖元之間,不過如果是更大的螢幕擷取畫面或螢幕擷取畫面的一部分,您應該相應增加或減少。The recommended width is between 600 and 700 pixels, though you should size up or down if it’s a dense screenshot or a fraction of a screenshot, respectively.

重要

在合併之前,您只能將影像上傳至您的分支存放庫。You can only upload images to your forked repo before merging. 因此,如果您打算將影像加入至文章,則必須先 使用 Visual Studio Code 將影像新增至分叉的 "images" 資料夾,或確定您已在網頁瀏覽器中完成下列動作:So, if you plan on adding images to an article, you'll need to use Visual Studio Code to add the images to your fork's "images" folder first or make sure you've done the following in a web browser:

  1. 派生 MicrosoftDocs/mixed 事實存放庫。Forked the MicrosoftDocs/mixed-reality repo.
  2. 已在您的分叉中編輯文章。Edited the article in your fork.
  3. 將您在文章中參考的影像上傳至您分叉中的「混合式事實-檔/影像」資料夾。Uploaded the images you're referencing in your article to the "mixed-reality-docs/images" folder in your fork.
  4. 建立 提取要求 ,以將您的分支合併至 MicrosoftDocs/mixed 事實 ' master ' 分支。Created a pull request to merge your fork into the MicrosoftDocs/mixed-reality 'master' branch.

若要瞭解如何設定您自己的分支存放庫,請依照指示來 建立新的文章To learn how to set up your own forked repo, follow the instructions for creating a new article.

預覽您的工作Previewing your work

透過網頁瀏覽器在 GitHub 中進行編輯時,您可以選取接近頁面頂端的 [ 預覽 ] 索引標籤,以在認可之前預覽您的工作。While editing in GitHub via a web browser, you can select the Preview tab near the top of the page to preview your work before committing.

注意

在 review.docs.microsoft.com 上預覽您的變更只適用于 Microsoft 員工Previewing your changes on review.docs.microsoft.com is only available to Microsoft employees

Microsoft 員工:一旦您的投稿合併到「主要」分支之後,您就可以在內容公開之前,先進行審核 https://review.docs.microsoft.com/windows/mixed-reality?branch=masterMicrosoft employees: once your contributions have been merged into the 'master' branch, you can review the content before it goes public at https://review.docs.microsoft.com/windows/mixed-reality?branch=master. 使用左邊資料行中的目錄來尋找您的文章。Find your article using the table of contents in the left column.

在瀏覽器中編輯和使用桌面用戶端編輯Editing in the browser vs. editing with a desktop client

在瀏覽器中編輯是進行快速變更的最簡單方式,不過,有幾個缺點:Editing in the browser is the easiest way to make quick changes, however, there are a few disadvantages:

  • 您不會收到拼寫檢查。You don't get spell-check.
  • 您不會在其他文章中取得任何智慧連結 (您必須手動輸入文章的檔案名) 。You don't get any smart-linking to other articles (you have to manually type the article's filename).
  • 上傳和參考影像可能很麻煩。It can be a hassle to upload and reference images.

如果您不想處理這些問題,請使用桌面用戶端(例如 Visual Studio Code ),並在參與時提供一些 實用的擴充 功能。If you'd rather not deal with these issues, use a desktop client like Visual Studio Code with a couple helpful extensions when contributing.

使用 Visual Studio CodeUsing Visual Studio Code

基於 上述原因,您可能會偏好使用桌面用戶端來編輯檔,而不是使用網頁瀏覽器。For the reasons listed above, you may prefer using a desktop client to edit documentation instead of a web browser. 我們建議使用 Visual Studio CodeWe recommend using Visual Studio Code.

設定Setup

請依照下列步驟設定 Visual Studio Code,以使用此存放庫:Follow these steps to configure Visual Studio Code to work with this repo:

  1. 在網頁瀏覽器中:In a web browser:
    1. 為您的電腦安裝 GitInstall Git for your PC.
    2. 安裝 Visual Studio CodeInstall Visual Studio Code.
    3. 如果您尚未這麼做,請先將MicrosoftDocs/混合的分支Fork MicrosoftDocs/mixed-reality if you haven't already.
    4. 在您的分支中,選取 [ 複製] 或 [下載 ] 並複製 URL。In your fork, select Clone or download and copy the URL.
  2. 在 Visual Studio Code 中建立分支的本機複製:Create a local clone of your fork in Visual Studio Code:
    1. 從 [ View ] 功能表選取 [ 命令 選擇區]。From the View menu, select Command Palette.
    2. 輸入 "Git: Clone"。Type "Git: Clone."
    3. 貼上您複製的 URL。Paste the URL you copied.
    4. 選擇要在電腦上儲存複本的位置。Choose where to save the clone on your PC.
    5. 在快顯視窗中選取 [ 開啟 存放庫]。Select Open repo in the pop-up.

編輯檔Editing documentation

您可以使用下列工作流程,利用 Visual Studio Code 對檔進行變更:Use the following workflow to make changes to the documentation with Visual Studio Code:

注意

使用 Visual Studio Code 也適用于 編輯建立 文章的所有指導方針,以及 編輯 Markdown 的基本概念All the guidance for editing and creating articles, and the basics of editing Markdown, from above applies when using Visual Studio Code as well.

  1. 請確定您複製的分支是最新的官方存放庫。Make sure your cloned fork is up to date with the official repo.

    1. 在網頁瀏覽器中,建立提取要求,以將最近的變更從 MicrosoftDocs/mixed 事實 ' master ' 中的其他參與者同步至您的分支 (確定箭號指向正確的) 方式。In a web browser, create a pull request to sync recent changes from other contributors in MicrosoftDocs/mixed-reality 'master' to your fork (make sure the arrow is pointing the right way).

      將 MicrosoftDocs/mixed 的變更同步至您的分叉

    2. 在 Visual Studio Code 中,選取 [同步處理] 按鈕,將新的已更新分支同步至本機複製。In Visual Studio Code, select the sync button to sync your freshly updated fork to the local clone.

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

  2. 使用 Visual Studio Code 在複製的存放庫中建立或編輯文章。Create or edit articles in your cloned repo using Visual Studio Code.

    1. 如有必要,請編輯一或多個發行項 (將影像新增至 [images] 資料夾) 。Edit one or more articles (add images to “images” folder if necessary).

    2. 儲存 Explorer 中的變更。Save changes in Explorer.

      在 Explorer 中選擇 [全部儲存]

    3. 當系統提示) 時,認可 原始檔控制 中的 所有 變更 (寫入認可訊息。Commit all changes in Source Control (write commit message when prompted).

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

    4. 選取 [ 同步 處理] 按鈕,將您的變更同步至 GitHub) 上 (您的原始來源。Select the sync button to sync your changes back to origin (your fork on GitHub).

      按一下 [同步] 按鈕

  3. 在網頁瀏覽器中,建立提取要求,將您分支中的新變更同步處理回 MicrosoftDocs/mixed 事實 ' master ' (確定箭號指向正確的) 方式。In a web browser, create a pull request to sync new changes in your fork back to MicrosoftDocs/mixed-reality 'master' (make sure the arrow is pointing the correct way).

    從您的分支建立提取要求至 MicrosoftDocs/mixed-事實

有用的延伸模組Useful extensions

編輯檔時,下列 Visual Studio Code 擴充功能很有用:The following Visual Studio Code extensions are useful when editing documentation:

  • Visual Studio Code 的檔 Markdown 延伸 模組:使用 Alt + M 來顯示檔撰寫選項的功能表,例如:Docs Markdown Extension for Visual Studio Code - Use Alt+M to bring up a menu of docs authoring options like:
    • 搜尋及參考您已上傳的影像。Search and reference images you've uploaded.
    • 新增像這樣的格式:清單、資料表和檔特定的呼叫 >[!NOTE]Add formatting like lists, tables, and docs-specific call-outs like >[!NOTE].
    • 搜尋和參考內部連結和書簽 (頁面) 中特定區段的連結。Search and reference internal links and bookmarks (links to specific sections within a page).
    • 格式化錯誤會反白顯示 (將滑鼠停留在錯誤上方,以深入瞭解) 。Formatting errors are highlighted (hover your mouse over the error to learn more).
  • 程式代碼拼寫檢查-拼錯的單字會加上底線;以滑鼠右鍵按一下拼錯的字組來變更它,或將它儲存至字典。Code Spell Checker - misspelled words will be underlined; right-click on a misspelled word to change it or save it to the dictionary.