--- name: azure-devops-wiki-markdown description: "Write, fix, or review Azure DevOps wiki Markdown, Mermaid, _TOC_, _TOSP_, details blocks, query tables, mentions, work-item links, KaTeX, videos, and code fences. Use for Azure DevOps surface quirks. Do NOT use for GitHub-only or non-Azure docs." compatibility: "Requires: python3. Optional network access for scripts/find_code_language.py refresh and live Highlight.js lookups." license: MIT --- # 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_]]`, `
`, `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 ` - Diagnose Azure DevOps-specific rendering surprises -> read `references/gotchas.md` ## Quick Reference | Task | Use | | --- | --- | | Create a wiki TOC | `[[_TOC_]]` | | Create a table of subpages | `[[_TOSP_]]` | | Force a line break inside a paragraph | end the line with two spaces before pressing Enter | | Add a Mermaid diagram to a wiki page | `::: mermaid` ... `:::` | | Add Azure Boards query results | `::: query-table ` ... `:::` | | Mention a user while editing in code | `@<{identity-guid}>` | | Link to another wiki page | `[Display text](/parent-page/child-page)` | | Force a line break in a wiki table cell | `
` | | Verify a code-fence alias | `python3 scripts/find_code_language.py typescript` | ## Reading Guide | Task | Read | | --- | --- | | Page structure, links, line breaks, tables, and standard wiki authoring | `references/syntax.md` | | Wiki-only features such as subpage tables, collapsible sections, query tables, mentions, KaTeX, and video embeds | `references/advanced-features.md` | | Proposal decision trees and rollout-plan examples | `references/decision-trees.md` | | Feature-by-surface support differences | `references/support-matrix.md` | | Supported Mermaid diagram types, syntax, and limitations | `references/mermaid.md` | | Safe code-fence aliases, ambiguous aliases, and local verification | `references/code-languages.md` | | Failure modes, symptoms, and fixes | `references/gotchas.md` | | Starter wiki page | `templates/wiki-page-starter.md` | | Starter advanced wiki page | `templates/wiki-page-advanced-starter.md` | | Starter proposal decision tree | `templates/decision-tree-proposal.md` | | Starter Mermaid snippets | `templates/mermaid-starter.md` | ## Operating Rules - Treat wiki pages as the safe target for Mermaid, `[[_TOC_]]`, `[[_TOSP_]]`, `query-table`, HTML tags, table-cell `
`, and collapsible `
` 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. `
` blocks need a blank line after ``, and multiple blocks need spacing after `
`, 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 ` 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.