使用英语阅读

通过


参与 HoloLens 文档

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

HoloLens 文档发布到 Microsoft Learn,后者使用 GitHub 风格的 Markdown 和 Markdig 功能。 在此存储库中编辑的内容将格式化为在 /hololens中显示的样式化页面。

本页介绍有关参与和链接到 Markdown 基础知识的基本步骤和指南。 感谢你的贡献!

可用存储库

存储库名称 URL
HoloLens MicrosoftDocs/HoloLens
混合现实 MicrosoftDocs/mixed-reality
VR 爱好者指南 MicrosoftDocs/mixed-reality/enthusiast-guide

开始之前

如果还没有帐户,则需要 创建 GitHub 帐户

备注

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

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

  • 为 GitHub 帐户创建 强密码。
  • 启用 双重身份验证
  • 恢复代码保存在安全的位置
  • 更新 公共配置文件设置。
    • 设置姓名,并考虑将 公共电子邮件 设置为 不要显示电子邮件地址
    • 建议上传个人资料图片,因为缩略图显示在Microsoft学习你参与的文章中。
  • 如果打算使用命令行,请考虑为 Windows设置 Git Credential Manager。 这样,每次做出贡献时,就不必输入密码。

发布系统与 GitHub 相关联,因此这些步骤非常重要。 你将使用 GitHub 别名将作为每个文章的作者或参与者列出。

编辑现有文章

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

  1. 导航到希望在“hololens”文件夹中编辑的文章。

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

    编辑文章。

    这将自动分叉默认分支,

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

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

    • 标题:查看文章时显示在浏览器选项卡中的页面标题。 页面标题用于 SEO 和索引,因此,除非有必要(尽管在文档公开之前这不太重要),否则不要更改标题。
    • 说明:编写文章内容的简要说明,从而提高 SEO 和发现。
    • 作者:如果你是页面的主要所有者,请在此处添加 GitHub 别名。
    • ms.author:如果你是页面的主要所有者,请在此处添加Microsoft别名(无需 @microsoft.com,只需别名)。
    • ms.date:如果要向页面添加主要内容,请更新日期,但不更新有关说明、格式设置、语法或拼写等修复。
    • 关键字:关键字有助于 SEO(搜索引擎优化)。 添加关键字(用逗号和空格分隔)特定于文章,但在列表中最后一个关键字之后没有标点符号。 无需添加应用于所有文章的全局关键字,因为这些关键字在其他地方进行管理。
  5. 完成文章编辑后,向下滚动并选择 建议文件更改

  6. 在下一页上,选择 创建拉取请求 将自动创建的分支合并到默认分支中,

  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 是要删除的旧文章的相对存储库路径。 请确保路径以 docset 开头(在本例中为 hololens),并包含 .md 文件扩展名。

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

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

如果添加重定向,请确保也删除旧文件。

创建新文章

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

  1. 使用右上角的 Fork 按钮,从 MicrosoftDocs/hololens 的默认分支 创建分支。

    分支(当前名为“main”)的默认分支。

  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. 选择 新的拉取请求,并将分支的主 分支合并到 MicrosoftDocs/hololens (确保箭头指向正确的目标)。

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

Markdown 基础知识

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

添加表

由于表格在 Microsoft Learn 上的样式,因此它们不会具有边框或自定义样式,即使尝试内联 CSS 也是如此。 它似乎在短时间内工作,但最终平台将去除表格的样式。 因此,提前计划并让表保持简单。 下面是一个网站,使 Markdown 表变得简单:[表生成器](https://www.tablesgenerator.com/markdown_tables)。

Docs Markdown Extension for Visual Studio Code 如果你使用的是 Visual Studio Code(请参阅下文), 编辑文档,也可轻松生成表。

添加图像

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

重要

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

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

若要了解如何设置自己的分叉存储库,请按照 创建新文章的说明

预览工作

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

备注

在 Microsoft Learn 上预览所做的更改仅适用于Microsoft员工。

Microsoft员工:当贡献已合并到默认分支中时,,可以在 </hololens?branch=main>公开之前查看内容。 使用左侧列中的目录查找文章。

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

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

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

如果你宁愿不处理这些问题,请使用桌面客户端(如 Visual Studio Code,在参与时 有用的扩展)。

使用 Visual Studio Code

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

设置

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

  1. 在 Web 浏览器中:
    1. 为电脑安装 Git
    2. 安装 Visual Studio Code
    3. Fork MicrosoftDocs/hololens(如果尚未这样做)。
    4. 在分支中,选择 克隆或下载 并复制 URL。
  2. 在 Visual Studio Code 中创建分支的本地克隆:
    1. 视图 菜单中,选择 命令面板
    2. 键入“Git: Clone”。”
    3. 粘贴复制的 URL。
    4. 选择在电脑上保存克隆的位置。
    5. 在弹出窗口中选择 打开存储库

编辑文档

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

备注

上述有关 编辑创建 文章以及编辑 Markdown的 基础知识的所有指南也适用于使用 Visual Studio Code。

  1. 确保克隆的分叉与官方存储库是最新的。

    1. 在 Web 浏览器中,创建拉取请求,以同步 MicrosoftDocs/hololens 默认分支中其他参与者的最新更改,分支(确保箭头指向正确的目标)。

      将 MicrosoftDocs/hololens 的更改同步到分支。

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

      单击“同步”按钮图像。

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

    1. 编辑一个或多个文章(如有必要,将图像添加到“images”文件夹)。

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

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

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

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

    4. 选择 同步 按钮,将更改同步回源(GitHub 上的分支)。

      单击“同步”按钮。

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

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

有用的扩展

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

  • 适用于 Visual Studio Code 的 Docs Markdown 扩展 - 使用 Alt+M 来显示Microsoft Learn 创作选项的菜单,例如:

    • 搜索和引用已上传的图像。
    • 添加列表、表格和标注等格式,如 >[!NOTE]
    • 搜索和引用内部链接和书签(指向页面内特定部分的链接)。
    • 突出显示格式错误(将鼠标悬停在错误上方以了解详细信息)。
  • 代码拼写检查器 - 拼写错误的单词将带下划线;右键单击拼写错误的单词以更改或将其保存到词典。