通过

.NET 文档的元数据和 Markdown 模板

此 dotnet/docs 模板包含有关设置元数据的 Markdown 语法和指南的示例。

创建 Markdown 文件时，将包含的模板复制到新文件，填写下面指定的元数据，并将上面的 H1 标题设置为文章标题。

Metadata

所需的元数据块位于以下示例元数据块中：

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents
  • 你必须在冒号 (:) 和元数据元素的值之间有一个空格。
  • 值（例如标题）中的冒号会中断元数据分析器。 在本例中，用双引号（例如， title: "Writing .NET Core console apps: An advanced step-by-step guide"）将标题括起来。
  • title：显示在搜索引擎结果中。 标题不应与 H1 标题中的标题相同，并且它应包含 60 个字符或更少。
  • 说明：总结文章的内容。 它通常显示在搜索结果页中，但它不用于搜索排名。 它的长度应为 115-145 个字符，包括空格。
  • author：作者字段应包含作者的 GitHub 用户名 。
  • ms.date：上次重大更新的日期。 更新现有文章，如果您已经查看并更新了整篇文档。 小修补程序（如拼写错误等）无须更新。

其他元数据会附加到每篇文章，但我们通常会在由docfx.json指定的文件夹级别应用大多数元数据值。

基本 Markdown、GFM 和特殊字符

可以在 Markdown 参考 文章中了解 Markdown、GitHub Flavored Markdown（GFM）和特定于 OPS 的扩展的基础知识。

Markdown 使用特殊字符（如 *、'和 #）进行格式设置。 如果要在内容中包含其中一个字符，则必须执行以下两项作之一：

  • 将反斜杠放在特殊字符前面以“转义”它（例如， \* 对于 *）。
  • 对字符使用 HTML 实体代码 （例如 * ，对于 *）。

文件名

文件名使用以下规则：

  • 仅包含小写字母、数字和连字符。
  • 无空格或标点符号字符。 使用连字符分隔文件名中的单词和数字。
  • 使用特定的动作动词，例如开发、购买、构建、故障排除。 不允许使用以“-ing”结尾的词。
  • 不使用小词 - 不包括a, and, the, in, or等。
  • 必须位于 Markdown 中并使用 .md 文件扩展名。
  • 保持文件名相对较短。 它们是文章的 URL 的一部分。

标题

使用句子样式大写。 始终将标题的第一个单词大写。

文本样式

Italics
适用于文件、文件夹、路径（对于较长的项目，单独拆分为一行）以及新术语。

Bold
可用于 UI 界面元素。

Code
用于内联代码、语言关键字、NuGet 包名称、命令行命令、数据库表和列名，以及不希望可点击的 URL。

有关定位点、内部链接、外部链接、指向其他文档的链接和代码包含的信息，请参阅关于链接的常规文章。

.NET 文档团队使用以下约定：

  • 在大多数情况下，我们使用相对链接，并不建议在链接中使用 ~/，因为相对链接会在 GitHub 上的源代码中被解析。 但是，每当链接到从属存储库中的文件时，我们都使用 ~/ 字符来提供路径。 由于从属存储库中的文件位于 GitHub 中的不同位置，因此无论链接是如何写入的，链接都不会正确解析为相对链接。
  • C# 语言规范和 Visual Basic 语言规范通过包含来自语言存储库的源代码被纳入 .NET 文档中。 markdown 源文件在 csharplang 和 vblang 存储库中管理。

指向规范的链接必须指向包含这些规范的源目录。 对于 C#，它是 ~/_csharplang/spec ，对于 VB，它是 ~/_vblang/spec，如以下示例所示：

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

生成系统具有一些扩展，允许我们链接到 .NET API，而无需使用外部链接。 使用以下语法之一：

  1. 自动链接： <xref:UID> 或 <xref:UID?displayProperty=nameWithType>

    查询 displayProperty 参数生成完全限定的链接文本。 默认情况下，链接文本仅显示成员或类型名称。

  2. Markdown 链接： [link text](xref:UID)

    当想要自定义显示的链接文本时使用。

示例：

  • <xref:System.String> 呈现为 字符串
  • <xref:System.String?displayProperty=nameWithType> 渲染成 System.String
  • [String class](xref:System.String) 呈现为 String 类

有关使用此表示法的详细信息，请参阅 “使用交叉引用”。

某些 UID 包含特殊字符 `、# 或 *，UID 值需要进行 HTML 编码，分别为 %60、%23 和 %2A。 有时会看到括号已编码，但这不是一项要求。

示例：

  • System.Threading.Tasks.Task'1 变为 System.Threading.Tasks.Task%601
  • System.Exception.#ctor 变为 System.Exception.%23ctor
  • System.Lazy'1.#ctor（System.Threading.LazyThreadSafetyMode） 变为 System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

如果在 UID 之后添加 * （或 %2A） ，则链接表示重载页，而不是特定 API。 例如，当你想要以泛型方式链接到 List<T>。BinarySearch 方法 页时，可以使用它，而不是使用特定重载的方式，例如 List<T>。BinarySearch（T，IComparer<T>）。 当成员未重载时，还可以使用 * 链接到成员页面;这样，就无需在 UID 中包含参数列表。

若要链接到具体的方法重载，必须包含方法中每个参数的完全限定类型名称。 例如， <xref：System.DateTime.ToString> 链接到无参数 DateTime.ToString 方法，而 <xref：System.DateTime.ToString（System.String，System.IFormatProvider）> 链接到 DateTime.ToString（String，IFormatProvider） 方法。

若要链接到泛型类型（如 System.Collections.Generic.List<T>），请使用 “（%60） 字符后跟泛型类型参数的数目。 例如，<xref:System.Nullable%601> 链接到 System.Nullable<T> 类型，而 <xref:System.Func%602> 链接到 System.Func<T，TResult> 的委托。

Code

包含代码的最佳方式是使用工作示例中的代码片段。 按照 contributing to .NET 文章中的说明创建您的示例。 包括来自完整程序的代码片段可确保所有代码都通过我们的持续集成 （CI） 系统运行。 但是，如果需要显示导致编译时间或运行时错误的内容，可以使用内联代码块。

有关用于在文档中显示代码的 Markdown 语法的信息，请参阅 如何在文档中包括代码。

映像

静态图像或动态 GIF

![this is the alt text](../images/Logo_DotNet.png)

链接图像

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Videos

可以在 Markdown 文件中嵌入 YouTube 视频。 若要获取视频的正确 URL，请右键单击视频，选择“ 复制嵌入代码”，然后从 <iframe> 元素复制 URL。

> [!VIDEO <youtube_video_link>]

例如：

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

learn.microsoft 扩展

learn.microsoft 为 GitHub Flavored Markdown 提供了一些附加扩展。

已核对的列表

自定义样式可用于列表。 可以用绿色勾选标记呈现列表。

> [!div class="checklist"]
>
> - How to create a .NET Core app
> - How to add a reference to the Microsoft.XmlSerializer.Generator package
> - How to edit your MyApp.csproj to add dependencies
> - How to add a class and an XmlSerializer
> - How to build and run the application

这呈现为：

  • 如何创建 .NET Core 应用
  • 如何添加对 Microsoft.XmlSerializer.Generator 包的引用
  • 如何编辑 MyApp.csproj 以添加依赖项
  • 如何添加类和 XmlSerializer
  • 如何生成和运行应用程序

可以在 .NET Core 文档中查看已检查列表的示例。

Buttons

按钮链接：

> [!div class="button"]
> [button links](dotnet-contribute.md)

这呈现为：

按钮链接

可以在 Visual Studio 文档中查看作中的按钮示例。

分步执行

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

可以在 C# 指南中看到分步执行的示例。

  • Last updated on