参与 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 现有文章 进行更新:
导航到希望在“hololens”文件夹中编辑的文章。
选择右上角的“编辑”按钮(铅笔图标)。
这将自动分叉默认分支,主。
根据 Markdown 基础知识编辑文章的内容。
更新每篇文章顶部的元数据:
- 标题:查看文章时显示在浏览器选项卡中的页面标题。 页面标题用于 SEO 和索引,因此,除非有必要(尽管在文档公开之前这不太重要),否则不要更改标题。
- 说明:编写文章内容的简要说明,从而提高 SEO 和发现。
- 作者:如果你是页面的主要所有者,请在此处添加 GitHub 别名。
- ms.author:如果你是页面的主要所有者,请在此处添加Microsoft别名(无需 @microsoft.com,只需别名)。
- ms.date:如果要向页面添加主要内容,请更新日期,但不更新有关说明、格式设置、语法或拼写等修复。
- 关键字:关键字有助于 SEO(搜索引擎优化)。 添加关键字(用逗号和空格分隔)特定于文章,但在列表中最后一个关键字之后没有标点符号。 无需添加应用于所有文章的全局关键字,因为这些关键字在其他地方进行管理。
完成文章编辑后,向下滚动并选择 建议文件更改。
在下一页上,选择 创建拉取请求 将自动创建的分支合并到默认分支中,主。
对要编辑的下一篇文章重复上述步骤。
如果更改将重命名或删除现有项目,请务必添加重定向。 这样,任何具有现有文章链接的人仍将位于正确的位置。 重定向由存储库根目录中 .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 在文档存储库中创建新文章:
使用右上角的 Fork 按钮,从 MicrosoftDocs/hololens 的默认分支 主创建分支。
在“hololens”文件夹中,选择右上方 创建新文件。
为项目创建页面名称(使用连字符而不是空格,不使用标点符号或撇号),并追加“.md”
重要
请确保从“hololens”文件夹中创建新文章。 可以通过在新文件名行中检查“/hololens/”来确认这一点。
在新页面顶部,添加以下元数据块:
--- title: description: author: ms.author: ms.date: ms.topic: article keywords: ---
按照前面所述填写相关元数据字段,编辑现有文章。
在文章底部添加一个
## See also
部分,其中包含指向其他相关文章的链接。完成后,选择 提交新文件。
选择 新的拉取请求,并将分支的主 主 分支合并到 MicrosoftDocs/hololens 主(确保箭头指向正确的目标)。
以下资源将帮助你了解如何使用 Markdown 语言编辑文档:
- 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 浏览器中执行以下操作:
- 分叉了 MicrosoftDocs/hololens 存储库。
- 编辑了分叉中的文章。
- 将文章中引用的图像上传到分叉中的“hololens/images”文件夹。
- 创建了一个 拉取请求,用于将分支合并到 MicrosoftDocs/hololens main 分支。
若要了解如何设置自己的分叉存储库,请按照 创建新文章的说明。
通过 Web 浏览器在 GitHub 中编辑时,可以选择页面顶部附近的 预览版 选项卡,在提交之前预览工作。
备注
在 Microsoft Learn 上预览所做的更改仅适用于Microsoft员工。
Microsoft员工:当贡献已合并到默认分支中时,主,可以在 </hololens?branch=main>公开之前查看内容。 使用左侧列中的目录查找文章。
在浏览器中编辑是进行快速更改的最简单方法,但存在一些缺点:
- 不会进行拼写检查。
- 您不会获得指向其他文章的任何智能链接(必须手动键入文章的文件名)。
- 上传和引用图像可能会很麻烦。
如果你宁愿不处理这些问题,请使用桌面客户端(如 Visual Studio Code,在参与时 有用的扩展)。
出于上述
按照以下步骤将 Visual Studio Code 配置为使用此存储库:
- 在 Web 浏览器中:
- 为电脑安装 Git。
- 安装 Visual Studio Code。
- Fork MicrosoftDocs/hololens(如果尚未这样做)。
- 在分支中,选择 克隆或下载 并复制 URL。
- 在 Visual Studio Code 中创建分支的本地克隆:
- 在 视图 菜单中,选择 命令面板。
- 键入“Git: Clone”。”
- 粘贴复制的 URL。
- 选择在电脑上保存克隆的位置。
- 在弹出窗口中选择 打开存储库。
使用以下工作流通过 Visual Studio Code 对文档进行更改:
备注
上述有关
确保克隆的分叉与官方存储库是最新的。
在 Web 浏览器中,创建拉取请求,以同步 MicrosoftDocs/hololens 默认分支中其他参与者的最新更改,主分支(确保箭头指向正确的目标)。
在 Visual Studio Code 中,选择同步按钮,将刚更新的分叉同步到本地克隆。
使用 Visual Studio Code 在克隆的存储库中创建或编辑文章。
编辑一个或多个文章(如有必要,将图像添加到“images”文件夹)。
在 资源管理器中保存 更改。
中选择“全部保存”
提交 源代码管理 中的所有 更改(出现提示时写入提交消息)。
中选择“全部提交”
选择 同步 按钮,将更改同步回源(GitHub 上的分支)。
在 Web 浏览器中,创建拉取请求,将分叉中的新更改同步回 MicrosoftDocs/hololens 主(确保箭头指向正确的目标)。
编辑文档时,以下 Visual Studio Code 扩展非常有用:
适用于 Visual Studio Code 的 Docs Markdown 扩展 - 使用 Alt+M 来显示Microsoft Learn 创作选项的菜单,例如:
- 搜索和引用已上传的图像。
- 添加列表、表格和标注等格式,如
>[!NOTE]
。 - 搜索和引用内部链接和书签(指向页面内特定部分的链接)。
- 突出显示格式错误(将鼠标悬停在错误上方以了解详细信息)。
代码拼写检查器 - 拼写错误的单词将带下划线;右键单击拼写错误的单词以更改或将其保存到词典。