企业官网建设流程全解析

This is a first level heading (H1)

【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml

This is a second level heading (H2)

...

This is a sixth level heading (H6)

三条具体规则： * **每个 Markdown 文件有且只有一个 H1 标题**，它应当是文件的标题，并且必须是文件的第一段内容。 * **应当避免层级过深的标题**：层级太多在阅读时难以区分，还会让目录（Table of Contents）变得冗长而混乱。 * **标题一律用 `#` 符号创建**，禁止使用 `===`（H1 下划线式）或 `---`（H2 下划线式）这种 setext 语法。 ### 仓库中的实际落地 * [docs/readme.md](https://link.gitcode.com/i/9aea2bc7a44e3198f1b26e4181243283) 与 [docs/building/developer-guide.md](https://link.gitcode.com/i/c1f0c8bb2b04405f5dd07dc708bc9cee) 均以单个 H1 开头（`# WinUI Developer Documentation`、`# Developer Guide`），全文不再出现第二个 H1，严格符合“唯一 H1”规则。 * 从源码结构看，[docs/readme.md](https://link.gitcode.com/i/9aea2bc7a44e3198f1b26e4181243283#L7-L15) 的目录只展开到 H2/H3 两级（`Getting Started` 下的 `Repo Layout`、`Developer Guide` 等），体现了“避免层级过深”的原则；而 [docs/building/developer-guide.md](https://link.gitcode.com/i/c1f0c8bb2b04405f5dd07dc708bc9cee#L9-L27) 的目录最深到三级嵌套（如 `Initializing CMD...` 下的 `Configuring the .NET version`），这是较长操作指南允许的深度上限示例。 ## 三、目录（Tables of Contents） 原文档说明： * 目录对长文档非常有用。创建方式是添加 **`[[TOC]]`** 标记——当页面中至少存在一个标题时，该标记处会生成目录。 * 目录应当放在**标题（H1）之后、其他任何标题之前**。 需要指出的是，`[[TOC]]` 是 ADO 环境的扩展标记。在当前公开仓库的 `docs/` 文档中（从仓库现状看），更常见的做法是**手写锚点式目录**，例如 [docs/readme.md](https://link.gitcode.com/i/9aea2bc7a44e3198f1b26e4181243283#L7-L15)： ```markdown ## Table of Contents - [Getting Started](#getting-started) - [Repo Layout](#repo-layout) - [Developer Guide](#developer-guide) ...

以及 docs/building/developer-guide.md 中更完整的三级嵌套目录。两者都遵循“紧跟 H1、置于正文标题之前”的位置要求，锚点写法（小写、去标点、空格转连字符）也与下文“书签链接”一节一致。在贡献时可按目标平台（ADO 用[[TOC]]，GitHub 用手写锚点目录）选择其中一种，但位置规则不变。

四、代码（Code）

原文档把代码排版分为三种形态：行内代码、代码块、占位符。

1. 行内代码

行内的“单词级”元素用反引号包裹：

code 风格的行内代码，用于：

• 引用附近代码块中出现的命名参数和变量；
• 指代属性、方法、类以及语言关键字。

例如 docs/building/developer-guide.md 中：

* In cmd, from the repo directory, run `init.cmd`. Or in PowerShell, run `init.ps1`. * Run `build.cmd`

这里init.cmd、init.ps1、build.cmd均对应仓库根目录真实存在的入口脚本（init.cmd、init.ps1、Build.cmd），行内代码用于精确指代可执行命令，是该用法的标准示范。

2. 代码块

代码块由三个反引号（ ```）包裹，两条硬性要求：

• 不要用纯缩进来创建代码块——四空格缩进在某些渲染器中是代码块，但在 ADO 的原始视图中行为不一致；
• 标注编程语言以启用语法高亮，且语言名必须小写：部分编辑器对大写也能工作，但 ADO 仅在语言标签小写时才在 raw view 中给出语法高亮。

原文档给出的完整示例（注意这是一个“代码块示例嵌套在代码块中”的写法，外层用四个反引号）：

```csharp public static void Log(string message) { _logger.LogInformation(message); } ```

仓库中的实际落地

docs/下大量文档遵循“三反引号 + 小写语言标签”的写法，例如 docs/design-notes/lightweight-bindings.md、docs/design-notes/TabTearOut-spec.md 中使用`cpp围栏，[docs/design-notes/mapControl-spec.md](https://link.gitcode.com/i/e88adeba1fb911a654540ff277d3c174) 中使用`csharp围栏。

代码块还常被用于流程示意。以 docs/building/developer-guide.md 的 “TL;DR for setup/build” 为例：

* Install the latest Visual Studio, then the .vsconfig file (details) * Clone the repo (details) * In cmd, from the repo directory, run `init.cmd`. Or in PowerShell, run `init.ps1`. * Run `build.cmd`

步骤用列表承载、命令用行内代码强调、每一步以(details)锚点回链到下文对应小节，这种“总览-详述”结构配合本文风格指南的标题与链接规则，构成了 WinUI 操作类文档的标准范式。

3. 占位符（Placeholders）

当示例代码中需要读者替换为自定义值时，用尖括号标记占位文本。原文档示例：

az group delete -n <ResourceGroupName>

在 WinUI 文档中，此类占位符常见于构建参数、路径与配置值示例中，例如写成build /p:Configuration=<BuildFlavor>的形式，让读者一眼识别哪些部分是待替换变量。

五、链接（Links）

原文档指出微软官方文档中关于链接的大部分规范同样适用于本仓库，并给出三条可执行规则：

1. 描述性链接文本

优先使用描述性的链接文本，而非“click here”（点击这里）这类无意义锚文本。这既是可用性要求，也对 SEO 与辅助技术（屏幕阅读器）友好。

2. 文件链接（跨文档引用）

• 所有文件路径一律使用正斜杠/，禁止反斜杠\；

• 同一目录内的文档互链：

  link text

• 链接到“当前目录的父目录下的某个子目录”中的文档时，使用相对路径：

  link text

仓库中的实际落地

docs/readme.md 是“正斜杠 + 目录相对路径”规则的集中示范：

To get an understanding of how the repository is laid out, see the [repo structure](https://link.gitcode.com/i/f4716f3724e933e43111b7ce2bf94f60) doc. The [developer guide](https://link.gitcode.com/i/c1f0c8bb2b04405f5dd07dc708bc9cee) contains information on how to do the day-to-day tasks in this repo... See [Testing In WinUI FAQ](https://link.gitcode.com/i/b06d66c64349586d38dd2886a321ffc2) and [WinUI CI Test System Overview](https://link.gitcode.com/i/7ac06133db9facda086c3202a82a8b18)...

分别演示了“同目录直链”（repo-structure.md）与“跨子目录链接”（./building/developer-guide.md、./testing/testing-FAQ.md）两种形态；而 docs/building/developer-guide.md 则演示了../common-errors-FAQ.md这种向上再进入的相对路径写法。

3. 书签链接（锚点）

• 链接当前文件内的标题：#后接标题的小写文本，去掉标点、空格替换为连字符：

  [Managed Disks](#managed-disks)

• 链接其他文件的标题：文件相对链接 +#+ 同样的小写连字符标题文本：

  Managed Disks

docs/building/developer-guide.md 的总览列表正是跨段落锚点链接的实例：每个步骤末尾的(details)链接形如[(details)](#install-visual-studio)、[(details)](#clone-the-winui-repo)，锚点均由目标标题（如Install Visual Studio）小写化、去标点、转连字符得到，可逐条对照验证规则。

六、加粗与斜体（Bold and Italic）

三种格式及其源码写法（转义形式用于在文档中展示语法本身）：

七、表格（Tables）

原文档指引：表格格式参照微软官方的 Markdown 参考文档中的 Tables 一节——Markdown 存在多种表格写法，但官方文档给出的那种在 ADO 中可以正常渲染。（官方文档中“使用自定义 div 类进行换行”的部分不适用于本仓库。）

标准的 ADO 兼容表格写法如下：

| Column A | Column B | |----------|----------| | value 1 | value 2 | | value 3 | value 4 |

仓库中确有按此格式落地的文档，例如 docs/building/developer-guide.md 等文档中使用管道符表格罗列参数与取值，可将其作为格式参照。

八、注释（Comments）

ADO 支持 HTML 注释，用于在不影响渲染的前提下注释掉文章中的某些片段：

<!--- Here's my comment --->

仓库中的实际落地

• docs/building/developer-guide.md 中保留有一行<!-- test comment 3 -->，是最直接的用法实例；
• docs/design-notes/下的大量 spec 文档（如 docs/design-notes/TabTearOut-spec.md、docs/design-notes/InfoBadge-spec.md）使用 HTML 注释标注待办与讨论点，例如<!--- TODO ... --->形式，用于在评审过程中“隐藏”草稿性文字而不干扰正式内容；
• docs/docs-style-guide.md 自身也用一段 HTML 注释记录了前文“嵌套代码块”示例存在的渲染 hack 原因，这是注释用于维护者备忘而非纯隐藏内容的第二种典型用途。

九、可读性（Readability）

原文档给出三条排版纪律：

1. 标题前后必须有空行

some text here. There will be a blank line before the next heading. ## Heading 2 Some more text after a blank line.

仓库实例：docs/building/developer-guide.md 中## Preparing the machine for building与### Disk Space前后均保留空行，标题块与正文、代码块之间都有清晰的留白。

2. 代码块前后必须有空行

即代码围栏 ``` 的上一行与下一行都应是空行，避免代码块与列表项、段落“粘连”导致渲染器误判归属。

3. 换行控制（Word wrapping）

ADO 的 raw markdown 视图不会自动折行，过长的行会使原始视图极难阅读。原文档的建议：

• 尽量在约 120 列处手动换行书写文档；
• 可借助 VS Code 的参考线（ruler）提示 120 列位置，或使用Rewrap等 VS Code 扩展批量重排；
• 两种合理的例外：
  • 对于超长文档，人工插入换行成本过高，可以保留长行；
  • 对于高频变动的文档，频繁改动换行位置会让 git 历史难以阅读，也可以先不换行。
• 一个折中策略：等文档的 PR 获得批准后再统一补换行——此时大部分内容修改已完成，后续历史将保持整洁。

十、对照仓库真实文档的自检清单

把原文档的八类规则汇总为可执行的贡献前检查项，并标注仓库内的验证出处：

【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml