azure-devops-wiki-markdown

Azure DevOps Wiki Markdown

将 Azure DevOps Markdown 问题导向合适的参考资料，并深入介绍仅 Wiki 支持的区块、兼容 Mermaid 的编写方式，以及代码围栏语言标识符。

基准资料：于 2026 年 4 月 9 日根据 Microsoft Learn 的 Azure DevOps Markdown 指南、Azure Repos Sprint 259 版本说明，以及 Highlight.js 支持的语言列表进行核对。支持情况描述的是该基准，不代表永久不支持，也不代表适用于每个 Server 版本。

决策树

你需要做什么？

常规且熟悉的语法可直接查阅快速参考。遇到平台特性、不确定的功能或渲染失败时，再加载相关参考资料；以下路由不要求每次编辑都同时阅读多个资料。

• 起草或修复普通 Wiki 页面 -> 阅读 references/syntax.md
• 检查某个功能是否适用于 Done、Widget、PR、README 或 Wiki -> 阅读 references/support-matrix.md
• 使用仅 Wiki 支持的功能，例如 [[_TOSP_]]、<details>、query-table、@ 提及、KaTeX 或视频嵌入 -> 阅读 references/advanced-features.md
• 为计划、推出、ADR 或依赖项讨论起草方案决策树 -> 阅读 references/decision-trees.md 和 templates/decision-tree-proposal.md
• 创建或调试 Mermaid 图表 -> 阅读 references/mermaid.md
• 选择代码围栏语言标签或别名 -> 阅读 references/code-languages.md，也可运行 python3 scripts/find_code_language.py <query>
• 诊断 Azure DevOps 特有的渲染异常 -> 阅读 references/gotchas.md

快速参考

任务	用法
创建 Wiki 目录	[[_TOC_]]
创建子页面表格	[[_TOSP_]]
在段落中强制换行	在按 Enter 前，在行尾添加两个空格
向 Wiki 页面添加 Mermaid 图表	::: mermaid ... :::
添加 Azure Boards 查询结果	::: query-table <query-guid> ... :::
在代码编辑时提及用户	@<{identity-guid}>
链接到另一个 Wiki 页面	[显示文本](/parent-page/child-page)
在 Wiki 表格单元格中强制换行	<br/>
验证代码围栏别名	python3 scripts/find_code_language.py typescript

阅读指南

任务	阅读
页面结构、链接、换行、表格和标准 Wiki 编写方式	references/syntax.md
仅 Wiki 支持的功能，例如子页面表格、可折叠区块、查询表格、提及、KaTeX 和视频嵌入	references/advanced-features.md
方案决策树和推出计划示例	references/decision-trees.md
不同界面的功能支持差异	references/support-matrix.md
支持的 Mermaid 图表类型、语法和限制	references/mermaid.md
安全的代码围栏别名、有歧义的别名及本地验证	references/code-languages.md
故障模式、症状和修复方法	references/gotchas.md
Wiki 页面起始模板	templates/wiki-page-starter.md
高级 Wiki 页面起始模板	templates/wiki-page-advanced-starter.md
方案决策树起始模板	templates/decision-tree-proposal.md
Mermaid 代码片段起始模板	templates/mermaid-starter.md

操作规则

• 将 Wiki 页面视为 Mermaid、[[_TOC_]]、[[_TOSP_]]、query-table、HTML 标签、表格单元格中的 <br/> 和可折叠 <details> 区块的安全目标。在假设这些功能在 PR、README、控件或 Done 字段中也同样适用之前，请先检查 references/support-matrix.md。
• 对于流程图样式的 Mermaid，优先使用 graph TD 或 graph LR。Microsoft 文档说明支持 Mermaid，但也明确指出 flowchart 语法在 Azure DevOps 中存在限制。
• 对于提案决策树，每个节点只放一个分支问题，并在图表下方列出建议、风险和下一步。
• 优先使用主流的代码围栏语言别名，例如 bash、powershell、json、yml、ts、tsx、python、csharp、cpp、sql 和 plaintext。对于边缘情况和别名重叠，请使用辅助脚本。
• 用户在源代码管理中直接编辑 Wiki Markdown，而不是使用浏览器编辑器时，应优先采用字面且有文档依据的语法，而不是仅适用于 UI 的说明。
• 保留宏、源代码字面量以及真实的查询或身份 GUID，不得改动。不要编造标识符，也不要为了行文风格而修复代码。模板用于展示语法和实用布局；应遵循用户要求的页面结构，不要强行套用入门模板的章节。

指引不足时

如果某项限制已经过时、不够充分或与目标不符，请使用其 Services/Server 版本选择器和相关发行说明，查阅 Microsoft Learn 当前文档。仅在确认目标支持且符合用户权限的情况下，才使用新支持的语法；Mermaid 或 Highlight.js 上游支持某项功能，本身并不能证明 Azure 也支持。若文档不可用或结论不明确，请说明这一缺口，并采用兼容的基线方案或经授权的渲染检查。提出对规范技能的修正时，应提供来源、目标版本和最小渲染示例或检查。不要为常见且已知的语法进行网络查找，也不要默默修改已安装的副本。

注意事项

1. Azure DevOps 对换行的要求比许多 Markdown 渲染器更严格。仅按 Enter 不会在段落内换行；应先在行尾添加两个空格。
2. Azure DevOps Wiki 页面中的 Mermaid 使用 ::: mermaid 区块，而不是三个反引号的 ```mermaid 围栏。
3. Azure DevOps 文档说明支持 Mermaid，但也警告 flowchart 语法受限。请将通用 Mermaid 流程图转换为 graph TD 或 graph LR。
4. [[_TOC_]] 和 [[_TOSP_]] 区分大小写，且每种标签在一个页面中只会渲染第一个实例。
5. <details><summary> 区块的 </summary> 后需要空行，多个区块之间的 </details> 后也需要留出间隔，否则页面可能无法正确渲染。
6. query-table 需要真实的 Azure Boards 查询 GUID，而不是查询名称或完整查询 URL。
7. 在代码中编辑时，@ 提及应使用 @<{identity-guid}>，而不是浏览器编辑器中可见的别名形式。
8. Highlight.js 将某些语言列为第三方包或存在歧义的别名。未经本地验证，不要保证少见标签能够高亮显示。
9. KaTeX 数学公式有针对拉取请求和 Wiki 文件的文档说明。未经单独检查，不要将此支持扩展到 README 文件或仪表板控件。

验证

• 对不确定的语言别名或别名重叠，请使用 python3 scripts/find_code_language.py <query> 进行检查。
• 维护此技能包时（而非编辑 Wiki 页面时），请从此技能目录运行 python3 scripts/validate.py .。
• 维护软件包时，请运行 python3 scripts/test_skill.py .，在本地验证评估结构和交叉引用。这两个软件包命令都无法证明用户的 Wiki 页面能够正确渲染。