贡献 HoloLens 文档

欢迎使用 HoloLens 文档! 在此存储库中创建或编辑的任何文章都将对公众可见。

HoloLens 文档显示在 docs.microsoft.com 平台上,该平台将 GitHub 风格的 Markdown 与 Markdig 功能结合使用。 在此存储库中编辑的内容将格式化为在 /hololens 中显示的风格化页面。

本页面介绍了基本供稿步骤和指导以及 Markdown 基础知识的链接。 感谢你的贡献!

可用的存储库

存储库名称 URL
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. 在“hololens”文件夹中导航到要编辑的文章。

  2. 选择右上角的编辑按钮(铅笔图标)。

    编辑文章。

    这会自动从默认分支 master 分叉出一个可处置的分支。

    注意

    本文提到了 master,但 Microsoft 不再使用该术语。 在从软件中删除该术语后,我们会将其从本文中删除。

  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": "hololens/old-article",
            "redirect_url": "/base-url/new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • source_path 是要删除的旧文章的相对存储库路径。 确保路径以文档集(在本例中为 hololens)开头,并包含 .md 文件扩展名。

  • redirect_url 是从旧文章指向新文章的相对公共 URL。 确保此 URL 不包含 并以 / 开头,因为它引用公共 URL 而不是存储库路径。 允许使用 #section 链接到新文章中的某个部分。 如有必要,还可以在此处使用另一个站点的绝对路径。

  • redirect_document_id 指示你是否要保留前一个文件的文档 ID。 默认值为 false。 如果想保留重定向文章中的 ms.documentid 属性值,请使用 true。 如果保留文档 ID,页面查看次数和排名等数据将传输到目标文章。 如果重定向主要用于重命名,而不是指向仅涵盖一些相同内容的不同项目,则执行此操作。

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

创建新文章

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

  1. 使用右上角的“分叉”按钮从 MicrosoftDocs/hololens 的默认分支 master 创建一个分叉。

    分叉默认分支(目前命名为“master”)。

    注意

    本文提到了 master,但 Microsoft 不再使用该术语。 在从软件中删除该术语后,我们会将其从本文中删除。

  2. 在“hololens”文件夹中,选择右上角的“创建新文件”。

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

    为新页面命名。

    重要

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

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

    ---
    title:
    description:
    author:
    ms.author:
    ms.date:
    ms.topic: article
    keywords:
    ---
    
  5. 按照前面编辑现有文章中的说明填写相关的元数据字段。

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

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

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

  9. 选择“新建拉取请求”,并将分叉的 master 分支合并到 MicrosoftDocs/hololens master(确保箭头指向正确的目标)。

    创建从分叉到 MicrosoftDocs/hololens 的拉取请求。

Markdown 基础知识

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

添加表

由于 docs.microsoft.com 样式表的形式,它们不会包含边框或自定义样式,即使你尝试使用内联 CSS。 样式表看起来会短暂工作一段时间,但最终平台会剥离出表中的样式。 因此,请提前规划并简化你的表。 这是一个可帮助你简化 Markdown 表的站点:[表生成器]](https://www.tablesgenerator.com/markdown_tables)。

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

添加图像

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

重要

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

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

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

预览工作

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

注意

只有 Microsoft 员工能够在 review.docs.microsoft.com 上预览更改

Microsoft 员工:将供稿合并到默认分支 master 后,可以在内容公开于 /hololens?branch=master 之前检查这些内容>。 使用左栏中的目录找到你的文章。

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

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

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

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

使用 Visual Studio Code

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

安装

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

  1. 在 Web 浏览器中:
    1. 安装适用于你 PC 的 Git
    2. 安装 Visual Studio Code
    3. 分叉 MicrosoftDocs/hololens(如果尚未这样做)。
    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/hololens 默认分支 master 中其他供稿人的最新更改同步到你的分叉(确保箭头指向正确的目标)。

      将 MicrosoftDocs/hololens 中的更改同步到你的分叉。

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

      单击同步按钮的插图。

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

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

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

      在资源管理器中选择“全部保存”

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

      在“源代码管理”中选择“全部提交”

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

      单击同步按钮。

  3. 在 Web 浏览器中,创建拉取请求以将分叉中的新更改同步回到 MicrosoftDocs/hololens master(确保箭头指向正确的目标)。

    创建从分叉到 MicrosoftDocs/hololens 的拉取请求。

有用的扩展

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

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