贡献混合现实开发人员文档

  • 项目

欢迎使用混合现实开发人员文档公共存储库！ 在此存储库中创建或编辑的任何文章都将对公众可见。

混合现实文档现在托管在 Microsoft Learn 上，该网站使用 GitHub 风格的 Markdown 以及 Markdig 功能。 在此存储库中编辑的内容将格式化为在 /windows/mixed-reality 中显示的风格化页面。

本页面介绍了基本供稿步骤和指导以及 Markdown 基础知识的链接。 感谢你的发布内容！

可用的存储库

存储库名称 URL
Azure Object Anchors MicrosoftDocs/azure-docs/articles/object-anchors
Azure 远程渲染 MicrosoftDocs/azure-docs/articles/remote-rendering
Azure 空间定位点 MicrosoftDocs/azure-docs/articles/spatial-anchors
HoloLens MicrosoftDocs/HoloLens
混合现实 MicrosoftDocs/mixed-reality
VR 爱好者指南 MicrosoftDocs/mixed-reality/enthusiast-guide

开始之前

如果没有 GitHub 帐户，需要创建一个 GitHub 帐户。

注意

如果你是 Microsoft 员工，请将你的 GitHub 帐户链接到你在 Microsoft 开源门户上的 Microsoft 别名。 加入“Microsoft”和“MicrosoftDocs”组织。

设置 GitHub 帐户时，我们还建议采取以下安全预防措施：

发布系统已绑定到 GitHub，因此这些步骤非常重要。 你将列为使用你的 GitHub 别名的每篇文章的作者或供稿人。

编辑现有文章

在 Web 浏览器中使用以下工作流通过 GitHub 更新现有文章：

  1. 在“mixed-reality-docs”文件夹中导航到要编辑的文章。

  2. 选择右上方的编辑按钮（铅笔图标），它将自动从“master”分支中分出可处理的分支。

    Edit an article.

  3. 根据 Markdown 基础知识编辑文章的内容。

  4. 更新每篇文章顶部的元数据：

    • title：查看文章时在浏览器标签中显示的页面标题。 页面标题用于 SEO 和索引，因此除非必要，否则不要更改标题（不过，在文档公开之前更改标题也无关紧要）。
    • description：编写文章内容的简短说明，这可以提高 SEO 排名和有助于发现你的文章。
    • author：如果你是页面的主要所有者，请在此处添加你的 GitHub 别名。
    • ms.author：如果你是页面的主要所有者，请在此处添加你的 Microsoft 别名（无需填写 @microsoft.com，只需添加别名）。
    • ms.date：如果要在页面中添加主要内容，而不是添加澄清内容或者纠正格式、语法或拼写等错误，请更新日期。
    • keywords：关键字有助于提高 SEO（搜索引擎优化）排名。 添加特定于文章的关键字，以逗号和空格分隔，但列表中的最后一个关键字之后不能有标点符号。 无需添加适用于所有文章的全局关键字，因为这些关键字将在其他位置进行管理。

  5. 编辑完文章后，向下滚动并选择“提出文件更改”。

  6. 在下一页面上，选择“创建拉取请求”以将自动创建的分支合并到“master”。

  7. 对要编辑的下一篇文章重复上述步骤。

重命名或删除现有文章

如果你的更改会重命名或删除现有文章，请务必添加重定向。 这样，拥有现有文章链接的任何人仍会定向到正确的位置。 重定向由存储库根目录中的 .openpublishing.redirection.json 文件管理。

若要在 .openpublishing.redirection.json 中添加重定向，请将一个条目添加到 redirections 数组：

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
    ...
    ]
}
  • source_path 是要删除的旧文章的相对存储库路径。 确保路径以 mixed-reality-docs 开头，以 .md 结尾。
  • redirect_url 是从旧文章指向新文章的相对公共 URL。 确保此 URL 不包含 mixed-reality-docs 或 .md，因为它引用的是公共 URL 而不是存储库路径。 允许使用 #section 链接到新文章中的某个部分。 如有必要，还可以在此处使用另一个站点的绝对路径。
  • redirect_document_id 指示你是否要保留前一个文件的文档 ID。 默认为 false。 如果想保留重定向文章中的 ms.documentid 属性值，请使用 true。 如果保留文档 ID，页面查看次数和排名等数据将传输到目标文章。 如果重定向主要用于重命名，而不是指向仅涵盖一些相同内容的不同项目，则执行此操作。

如果添加重定向，请务必删除旧文件。

创建新文章

在 Web 浏览器中使用以下工作流通过 GitHub 在文档存储库中创建新文章：

  1. 创建 MicrosoftDocs/mixed-reality 的“master”分支的分支（使用右上角的“分支”按钮）。

    Creating a fork.

  2. 在“mixed-reality-docs”文件夹中，选择右上角的“创建新文件”。

  3. 为文章创建一个页面名称（使用连字符而不是空格，不要使用标点符号或撇号）并追加“.md”

    Name your new page.

    重要

    确保在“mixed-reality-docs”文件夹内部创建新文章。 可以通过检查新文件名行中的“/mixed-reality-docs/”来确认这一点。

  4. 在新页面的顶部，添加以下元数据块：

    ---
title:
description:
author:
ms.author:
ms.date:
ms.topic: article
keywords:
---

  5. 按照以上部分的说明填写相关的元数据字段。

  6. 使用 Markdown 基础知识撰写文章内容。

  7. 在文章底部添加一个 ## See also 部分，其中包含指向其他相关文章的链接。

  8. 完成后，选择“提交新文件”。

  9. 选择“新建拉取请求”，并将分支的“master”分支合并到 MicrosoftDocs/mixed-reality 的“master”（确保箭头指向正确的方向）。

    Create pull request from your fork into MicrosoftDocs/mixed-reality

Markdown 基本信息

以下资源可帮助你了解如何使用 Markdown 语言来编辑文档：

添加表

由于 Microsoft 技术文档设置表样式的方式，即使你尝试内联 CSS，它们也不会有边框或自定义样式。 样式表看起来会短暂工作一段时间，但最终平台会剥离出表中的样式。 因此，请提前规划并简化你的表。 这是一个可帮助你简化 Markdown 表的站点。

如果使用 Visual Studio Code（参阅下文）来编辑文档，Visual Studio Code 的 Docs Markdown 扩展也可以简化表格的生成。

添加图像

需要将图像上传到存储库中的“mixed-reality-docs/images”文件夹，然后在文章中正确地引用它们。 图像将自动以全尺寸显示，这意味着大图像将填满文章的整个宽度。 我们建议在上传图像之前预先调整图像大小。 建议的宽度为 600 到 700 像素，但如果图像是高密度的屏幕截图或只是屏幕截图的一小部分，则应该分别放大或缩小尺寸。

重要

只能在合并之前将图像上传到分叉的存储库。 因此，如果你打算将图像添加到文章中，需要先使用 Visual Studio Code 将图像添加到分叉的“images”文件夹，或者确保已在 Web 浏览器中：

  1. 已对 MicrosoftDocs/mixed-reality 存储库进行分叉处理。
  2. 编辑了分叉中的文章。
  3. 已将在文章中引用的图像上传到分叉中的“mixed-reality-docs/images”文件夹。
  4. 已创建一个拉取请求以将分叉合并到 MicrosoftDocs/mixed-reality 的“master”分支中。

若要了解如何设置自己的分叉存储库，请按照有关创建新文章的说明进行操作。

预览工作

通过 Web 浏览器在 GitHub 中进行编辑时，可以选择页面顶部附近的“预览”选项卡，以便在提交之前预览你的工作。

注意

“预览暂存更改”功能仅适用于 Microsoft 员工

Microsoft 员工：在你的贡献内容合并到主分支后，你可以在内容公开之前在 /windows/mixed-reality?branch=main 查看相应内容。 使用左栏中的目录找到你的文章。

在浏览器中进行编辑还是使用桌面客户端进行编辑

在浏览器中进行编辑是快速完成更改的最简单方法，但也有一些缺点：

  • 无法进行拼写检查。
  • 无法获得其他文章的任何智能链接（必须手动键入文章的文件名）。
  • 上传和引用图像可能很麻烦。

如果你不想面对这些问题，可以在供稿时使用 Visual Studio Code 之类的桌面客户端和几个有用的扩展。

使用 Visual Studio Code

由于上面列出的原因，你可能更偏好使用桌面客户端而不是 Web 浏览器来编辑文档。 建议使用 Visual Studio Code。

安装

按照以下步骤配置 Visual Studio Code 以使用此存储库：

  1. 在 Web 浏览器中：
    1. 安装适用于你 PC 的 Git。
    2. 安装 Visual Studio Code。
    3. 分叉 MicrosoftDocs/mixed-reality（如果尚未这样做）。
    4. 在分叉中，选择“克隆或下载”并复制 URL。
  2. 在 Visual Studio Code 中创建分叉的本地克隆：
    1. 在“视图”菜单中选择“命令面板”。
    2. 键入“Git: Clone”。
    3. 粘贴复制的 URL。
    4. 在 PC 上选择该克隆要保存到的位置。
    5. 在弹出窗口中选择“打开存储库”。

编辑文档

使用以下工作流通过 Visual Studio Code 对文档进行更改：

注意

使用 Visual Studio Code 时，以上所有关于编辑和创建文章的指导以及有关编辑 Markdown 的基础知识也同样适用。

  1. 确保克隆的分叉的更新状态与官方存储库保持相同。

    1. 在 Web 浏览器中，创建拉取请求以将 MicrosoftDocs/mixed-reality 的“master”中其他供稿人的最新更改同步到你的分叉（确保箭头指向正确的方向）。

      Sync changes from MicrosoftDocs/mixed-reality to your fork

    2. 在 Visual Studio Code 中，选择同步按钮以将更新后的全新分叉同步到本地克隆。

      Click the sync button image

  2. 使用 Visual Studio Code 在克隆的存储库中创建或编辑文章。

    1. 编辑一篇或多篇文章（如果需要，请将图像添加到“images”文件夹）。

    2. 在“资源管理器”中保存更改。

      Choose

    3. 在“源代码管理”中提交所有更改（出现提示时编写提交消息）。

      Choose

    4. 选择“同步”按钮将更改同步回到源（GitHub 上你的分叉）。

      Click the sync button

  3. 在 Web 浏览器中，创建拉取请求以将分叉中的新更改同步回到 MicrosoftDocs/mixed-reality 的“master”（确保箭头指向正确的方向）。

    Create pull request from your fork into MicrosoftDocs/mixed-reality

有用的扩展

编辑文档时，以下 Visual Studio Code 扩展非常有用：

  • Visual Studio Code 的文档 Markdown 扩展 - 按 Alt+M 即可调出一个包含文档创作选项的菜单，如下所示：
    • 搜索和引用上传的图像。
    • 添加格式，例如列表、表和文档特定的标注（如 >[!NOTE]）。
    • 搜索和引用内部链接与书签（链接到页面内部的特定部分）。
    • 格式错误会突出显示（将鼠标悬停在错误上可了解详细信息）。
  • 代码拼写检查器 - 拼错的单词带有下划线；右键单击拼错的单词可进行更改或将其保存到字典中。