对混合现实开发人员文档进行贡献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.

混合现实文档现在位于 docs.microsoft.com 平台上,后者使用 GitHub 风格 Markdown 和 Markdig 功能。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/混合-现实/发烧-指南MicrosoftDocs/mixed-reality/enthusiast-guide
HoloLensHoloLens MicrosoftDocs/HoloLensMicrosoftDocs/HoloLens

准备工作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

使用以下工作流,在 web 浏览器中通过 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.
    • 女士:如果你是页面的主要所有者,请在此处添加你的 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.js管理。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 指示是否要保留以前文件中的文档 ID。redirect_document_id indicates whether you would like to keep the document ID from the previous file. 默认值为 falseThe default is false. true如果要保留 ms.documentid 重定向的项目中的属性值,请使用。Use true if you want to preserve the ms.documentid attribute value from the redirected article. 如果保留文档 ID,数据(如页面视图和分级)将传输到目标文章。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

使用以下工作流在 web 浏览器中通过 GitHub 在文档存储库中 创建新项目Use the following workflow to create new articles in the documentation repo via GitHub in a web browser:

  1. 使用右上方) 中的 " 分叉 " 按钮,创建 MicrosoftDocs/mixed reality "master" 分支 (分叉。Create a fork off the MicrosoftDocs/mixed-reality 'master' branch (using the Fork button in the top right).

    将主分支分叉。

  2. 在 "混合现实文档" 文件夹中,选择右上方的 " 新建文件 "。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"

    命名新页。

    重要

    请确保在 "mixed reality-文档" 文件夹中创建新项目。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. 选择 " 新建拉取请求 ",并将分支的 "master" 分支合并到 MicrosoftDocs/mixed reality "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/混合现实的拉取请求

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 (请参阅) 下面的 "Markdown" 文档中的 "文档" Visual Studio Code 扩展,以编辑该文档。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" 文件夹,或者确保已在 web 浏览器中完成以下操作: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 reality 存储库。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 reality "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

通过 web 浏览器在 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 员工:将你的贡献合并到 "master" 分支后,你可以在内容公开之前查看内容 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

出于 上面列出的原因,您可能更倾向于使用桌面客户端编辑文档而不是 web 浏览器。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. 在 web 浏览器中: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. 从 " 视图 " 菜单中选择 " 命令面板"。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. 在 web 浏览器中,创建一个拉取请求,将 MicrosoftDocs/mixed reality "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/混合事实同步到你的分支

    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. 资源管理器保存 更改。Save changes in 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. 在 web 浏览器中,创建一个拉取请求,将分支中的新更改同步回 MicrosoftDocs/mixed reality "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/混合现实的拉取请求

有用的扩展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.