通过

为 Internet Information Services (IIS) 文档贡献内容

本文档介绍了为 IIS 文档站点上托管的文章和代码示例贡献内容的过程。 贡献可以是版式修复，也可以很复杂，例如撰写新文章。

如何提出简单的更正和建议

文章作为 Markdown 文件存储在存储库中。 通过选择浏览器窗口右上角的“编辑”链接，可以在浏览器中对 Markdown 文件的内容进行小的更改。 （在狭窄的浏览器窗口中，需要展开“选项”栏才能看到“编辑”链接。）按照说明创建拉取请求 (PR)。 我们将对拉取请求进行评审并接受相关请求或提出更改建议。

如何提出更复杂的提交

需要对 Git 和 GitHub.com 有基本的理解。

  • 打开问题，描述想要执行的操作，例如更改现有文章或创建一个新文章。 请等待团队批准后再投入时间参与进来。
  • 为 iis-docs 存储库创建分支，并为所做更改创建一个分支。
  • 将拉取请求 (PR) 与更改一起提交到主干。
  • 如果 PR 分配到的标签为“cla-required”，则完成贡献许可协议 (CLA)
  • 对 PR 请求反馈进行响应。

有关此过程导致发布新文章的示例，请参阅 .NET 存储库中的问题 67 和拉取请求 798。 新文章为编写代码。

Markdown 语法

文章采用 DocFx 风格的 Markdown 编写，它是 GitHub 风格的 Markdown (GFM) 的超集。 有关文档中常用的 UI 功能的 DFM 语法示例，请参阅 .NET 存储库风格指南中的元数据和 Markdown 模板。

文件夹结构约定

对于每个 Markdown 文件，可能存在图像文件夹和示例代码文件夹。 例如，如果文章为 /extensions/advanced-logging-module/advanced-logging-for-iis-client-logging.md，则图像位于 extensions/advanced-logging-module /advanced-logging-for-iis-client-loggin/_static，示例应用程序项目文件位于 extensions/advanced-logging-module/advanced-logging-for-iis-client-loggin/samples。 /advanced-logging-for-iis-client-logging.md 文件中的图像由以下 Markdown 渲染。

![description of image for alt attribute](advanced-logging-for-iis-client-logging/_static/imagename.png)

所有图像都应包含替代文本。

Markdown 文件名和图像文件名应全部小写。

代码片段

文章经常包含代码片段来说明要点。 DFM 允许将代码复制到 Markdown 文件或引用单独的代码文件。 请尽可能使用单独的代码文件，以最大限度地减少代码中出错的可能性。 代码文件应存储在使用示例项目的上面所述的文件夹结构的存储库中。

下面是会在 configuration.md 文件中使用的 DFM 代码片段语法的一些示例。

将整个代码文件呈现为代码段：

[!code-csharp[Main](configuration/sample/Program.cs)]

使用行号将文件的一部分呈现为代码片段：

[!code-csharp[Main](configuration/sample/Program.cs?range=1-10,20,30,40-50]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=1-10,20,30,40-50]

有关 C# 代码片段，请参阅 C# 区域。 请尽可能使用区域而不是行号，因为代码文件中的行号往往会更改，并与 Markdown 中引用的行号不同步。 可以嵌套 C# 区域，如果引用外部区域，内部 #region 和 #endregion 指令不会在代码片段中呈现。

呈现名为 “snippet_Example” 的 C# 区域：

[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example)]

突出显示呈现的代码段中选定的行（通常呈现为黄色背景）：

[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example&highlight=1-3,10,20-25)]
[!code-csharp[Main](configuration/sample/Program.cs?range=10-20&highlight=1-3]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=10-20&highlight=1-3]
[!code-javascript[Main](configuration/sample/Project.json?range=10-20&highlight=1-3]

使用 DocFX 测试更改

使用 DocFX 命令行工具测试更改，这将创建站点的本地托管版本。 DocFX 不呈现为 learn.microsoft.com 创建的样式和站点扩展。

DocFX 需要使用 .NET Framework（对于 Windows）或 Mono（对于 Linux 或 macOS）。

Windows 说明

  • 从 DocFX 发布下载并解压缩 “docfx.zip”。

  • 将 DocFX 添加到路径。

  • 在命令行窗口中，导航至包含 docfx.json 文件的相应文件夹 (iis-docs/iis)，然后运行以下命令：

    docfx -t default --serve

  • 在浏览器中导航到 http://localhost:8080。

Mono 说明

  • 使用 Homebrew 安装 Mono - brew install mono。

  • 立即下载 DocFX 的最新版本。

  • 提取到 \bin\docfx。

  • 为 docfx 创建一个别名：

    function docfx {
  mono $HOME/bin/docfx/docfx.exe
}

function docfx-serve {
  mono $HOME/bin/docfx/docfx.exe serve _site
}

  • 在 iis-docs\iis 目录中运行 docfx 以生成站点，在 http://localhost:8080 上运行 docfx-serve 以查看站点。

语音和声调

我们的目标是编写被广泛受众所理解的易懂文档。 为此，我们编写了写作风格指南，请参与者遵守。 有关详细信息，请参阅 .NET 存储库中的 语气和语调指南。

重定向

如果删除某篇文章、更改文章的文件名或将其移到另一个文件夹，请创建一个重定向，确保将该文收藏为书签的人不会收到 404 错误。 向主重定向文件添加添加重定向。

  • Last updated on