Azure Devops Wiki Markdown

Azure DevOps Wiki Markdown

Route Azure DevOps Markdown questions to the right reference, with extra depth on wiki-only blocks, Mermaid-safe authoring, and code-fence language identifiers.

Verified against Microsoft Learn Azure DevOps Markdown guidance, the Azure Repos Sprint 259 release note, and the current Highlight.js supported-language table on April 9, 2026.

Decision Tree

What do you need to do?

• Draft or repair a normal wiki page -> read references/syntax.md
• Check whether a feature works in Done, Widget, PR, README, or Wiki -> read references/support-matrix.md
• Use wiki-only features such as [[_TOSP_]], <details>, query-table, @ mentions, KaTeX, or video embeds -> read references/advanced-features.md
• Draft a proposal decision tree for a plan, rollout, ADR, or dependency discussion -> read references/decision-trees.md and templates/decision-tree-proposal.md
• Create or debug a Mermaid diagram -> read references/mermaid.md
• Pick a fenced-code language tag or alias -> read references/code-languages.md and optionally run python3 scripts/find_code_language.py <query>
• Diagnose Azure DevOps-specific rendering surprises -> read references/gotchas.md

Quick Reference

Reading Guide

Operating Rules

• Treat wiki pages as the safe target for Mermaid, [[_TOC_]], [[_TOSP_]], query-table, HTML tags, table-cell <br/>, and collapsible <details> sections. Check references/support-matrix.md before assuming the same feature works in PRs, READMEs, widgets, or Done fields.
• For flowchart-style Mermaid, prefer graph TD or graph LR. Microsoft documents Mermaid support but explicitly calls out flowchart syntax as a limitation in Azure DevOps.
• For proposal decision trees, keep one branching question per node and put the recommendation, risks, and next step below the diagram.
• Prefer mainstream code-fence aliases such as bash, powershell, json, yml, ts, tsx, python, csharp, cpp, sql, and plaintext. Use the helper script for edge cases and alias overlaps.
• When a user edits wiki Markdown directly in source control instead of the browser editor, favor literal, documented syntax over UI-only instructions.

Gotchas

1. Azure DevOps line breaks are stricter than many Markdown renderers. Pressing Enter alone does not create an in-paragraph line break; add two trailing spaces first.
2. Mermaid in Azure DevOps wiki pages uses ::: mermaid blocks, not triple-backtick ```mermaid fences.
3. Azure DevOps documents Mermaid support but also warns that flowchart syntax is limited. Convert generic Mermaid flowcharts to graph TD or graph LR.
4. [[_TOC_]] and [[_TOSP_]] are case-sensitive, and only the first instance of each tag renders on a page.
5. <details><summary> blocks need a blank line after </summary>, and multiple blocks need spacing after </details>, or the page can render incorrectly.
6. query-table needs a real Azure Boards query GUID, not the query name or the full query URL.
7. When editing in code, @ mentions use @<{identity-guid}>, not the visible alias form from the browser editor.
8. Highlight.js lists some languages as third-party packages or ambiguous aliases. Do not promise highlighting for uncommon tags until you verify them locally.
9. KaTeX math is documented for pull requests and wiki files. Do not project that support onto README files or dashboard widgets without a separate check.

Verification

• Run python3 scripts/find_code_language.py <query> when a user asks whether a language alias exists or whether an alias is ambiguous.
• Run python3 scripts/validate.py . from this skill directory after edits.
• Run python3 scripts/test_skill.py . to verify eval structure and cross-references locally.