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

2023-03-21

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

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

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

可用的存储库

存储库名称	URL
Azure 远程渲染	MicrosoftDocs/azure-docs/articles/remote-rendering
HoloLens	MicrosoftDocs/HoloLens
混合现实	MicrosoftDocs/mixed-reality
VR 爱好者指南	MicrosoftDocs/mixed-reality/enthusiast-guide

开始之前

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

注意

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

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

创建 Github 帐户的强密码。
启用双因素身份验证。
将恢复代码保存在安全的位置。
更新公共个人资料设置。
- 设置姓名，并考虑将“公共电子邮件”设置为“不显示我的电子邮件地址”。
- 建议上传个人资料图片，因为贡献的文档页面上会显示缩略图。
如果你打算使用命令行，请考虑设置 Git Credential Manager for Windows。这样，就不需要在每次供稿时都输入密码。

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

编辑现有文章

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

在“mixed-reality-docs”文件夹中导航到要编辑的文章。
选择右上方的编辑按钮（铅笔图标），它将自动从“master”分支中分出可处理的分支。
根据 Markdown 基础知识编辑文章的内容。
更新每篇文章顶部的元数据：
- title：查看文章时在浏览器标签中显示的页面标题。页面标题用于 SEO 和索引，因此除非必要，否则不要更改标题（不过，在文档公开之前更改标题也无关紧要）。
- description：编写文章内容的简短说明，这可以提高 SEO 排名和有助于发现你的文章。
- author：如果你是页面的主要所有者，请在此处添加你的 GitHub 别名。
- ms.author：如果你是页面的主要所有者，请在此处添加你的 Microsoft 别名（无需填写 @microsoft.com，只需添加别名）。
- ms.date：如果要在页面中添加主要内容，而不是添加澄清内容或者纠正格式、语法或拼写等错误，请更新日期。
- keywords：关键字有助于提高 SEO（搜索引擎优化）排名。添加特定于文章的关键字，以逗号和空格分隔，但列表中的最后一个关键字之后不能有标点符号。无需添加适用于所有文章的全局关键字，因为这些关键字将在其他位置进行管理。
编辑完文章后，向下滚动并选择“提出文件更改”。
在下一页面上，选择“创建拉取请求”以将自动创建的分支合并到“master”。
对要编辑的下一篇文章重复上述步骤。

重命名或删除现有文章

如果你的更改会重命名或删除现有文章，请务必添加重定向。这样，拥有现有文章链接的任何人仍会定向到正确的位置。重定向由存储库根目录中的 .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 在文档存储库中创建新文章：

创建 MicrosoftDocs/mixed-reality 的“master”分支的分支（使用右上角的“分支”按钮）。
在“mixed-reality-docs”文件夹中，选择右上角的“创建新文件”。
为文章创建一个页面名称（使用连字符而不是空格，不要使用标点符号或撇号）并追加“.md”

重要

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

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

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

按照以上部分的说明填写相关的元数据字段。
使用 Markdown 基础知识撰写文章内容。
在文章底部添加一个 ## See also 部分，其中包含指向其他相关文章的链接。
完成后，选择“提交新文件”。
选择“新建拉取请求”，并将分支的“master”分支合并到 MicrosoftDocs/mixed-reality 的“master”（确保箭头指向正确的方向）。

Markdown 基本信息

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

添加表

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

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

添加图像

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

重要

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

已对 MicrosoftDocs/mixed-reality 存储库进行分叉处理。
编辑了分叉中的文章。
已将在文章中引用的图像上传到分叉中的“mixed-reality-docs/images”文件夹。
已创建一个拉取请求以将分叉合并到 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 以使用此存储库：

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

编辑文档

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

注意

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

确保克隆的分叉的更新状态与官方存储库保持相同。
1. 在 Web 浏览器中，创建拉取请求以将 MicrosoftDocs/mixed-reality 的“master”中其他供稿人的最新更改同步到你的分叉（确保箭头指向正确的方向）。
2. 在 Visual Studio Code 中，选择同步按钮以将更新后的全新分叉同步到本地克隆。
使用 Visual Studio Code 在克隆的存储库中创建或编辑文章。
1. 编辑一篇或多篇文章（如果需要，请将图像添加到“images”文件夹）。
2. 在“资源管理器”中保存更改。
3. 在“源代码管理”中提交所有更改（出现提示时编写提交消息）。
4. 选择“同步”按钮将更改同步回到源（GitHub 上你的分叉）。
在 Web 浏览器中，创建拉取请求以将分叉中的新更改同步回到 MicrosoftDocs/mixed-reality 的“master”（确保箭头指向正确的方向）。

有用的扩展

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

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