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 -> readreferences/advanced-features.md - Draft a proposal decision tree for a plan, rollout, ADR, or dependency discussion -> read
references/decision-trees.mdandtemplates/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.mdand optionally runpython3 scripts/find_code_language.py <query> - 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 <query-guid> ... ::: |
| 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 | <br/> |
| 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<br/>, and collapsible<details>sections. Checkreferences/support-matrix.mdbefore assuming the same feature works in PRs, READMEs, widgets, or Done fields. - For flowchart-style Mermaid, prefer
graph TDorgraph LR. Microsoft documents Mermaid support but explicitly calls outflowchartsyntax 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, andplaintext. 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
- 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.
- Mermaid in Azure DevOps wiki pages uses
::: mermaidblocks, not triple-backtick```mermaidfences. - Azure DevOps documents Mermaid support but also warns that
flowchartsyntax is limited. Convert generic Mermaid flowcharts tograph TDorgraph LR. [[_TOC_]]and[[_TOSP_]]are case-sensitive, and only the first instance of each tag renders on a page.<details><summary>blocks need a blank line after</summary>, and multiple blocks need spacing after</details>, or the page can render incorrectly.query-tableneeds a real Azure Boards query GUID, not the query name or the full query URL.- When editing in code,
@mentions use@<{identity-guid}>, not the visible alias form from the browser editor. - Highlight.js lists some languages as third-party packages or ambiguous aliases. Do not promise highlighting for uncommon tags until you verify them locally.
- 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.
More from jpcaparas/skills
markdown-new
Use markdown.new when the user explicitly wants markdown.new, Cloudflare Markdown for Agents, URL-to-Markdown conversion, file-to-Markdown conversion, crawl-to-Markdown, or the hosted markdown.new editor. Trigger on: 'markdown.new', 'convert this URL to markdown', 'crawl this docs site into markdown', 'file to markdown', 'upload this PDF to markdown', 'markdown.new API', or 'markdown editor'. Do NOT trigger for generic web search/scraping when another tool is enough, or for editing local Markdown without using the markdown.new service.
32skill-creator-advanced
Advanced skill creator for mission-critical, installable skills — API wrappers, progressively-disclosed technical documentation, CLI tool integrations, and complex multi-reference skills. Use when creating or improving skills that demand rigorous progressive disclosure, verified examples, tested operations, cross-harness compatibility, smart placement into the right repo-local or global skills directory, and self-improvement feedback loops. Triggers on: 'advanced skill', 'create API skill', 'create wrapper skill', 'production skill', 'installable skill', 'improve this skill for progressive disclosure', 'rigorous skill', 'mission-critical skill', or when skill-creator's output needs to be more thorough. Also use when upgrading an existing skill to production quality.
32ripgrep
Prefer ripgrep (`rg`) for text search, recursive codebase search, ignore-aware grep replacement, filename discovery via `rg --files`, and machine-readable search output. Use when the user asks to search for text, find occurrences, inspect a large tree, locate files by name or pattern, or when `grep`, `grep -R`, `find | grep`, or manual file reads would be slower. Triggers on: 'search for', 'find occurrences', 'grep', 'grep -R', 'ripgrep', 'rg', 'find files', 'look for pattern'. Do NOT trigger for reading entire files, structured JSON queries better handled by `jq`, or filesystem metadata tasks that need `find` or `fd`.
29synthetic-search
Use this skill when the user explicitly wants Synthetic Search, the Synthetic API, `api.synthetic.new`, `SYNTHETIC_API_KEY`, or zero-data-retention web search with raw `curl`/`jq` examples. It covers live-verified search requests, quota checks, and a zero-dependency Node helper for readable output. Triggers on: 'Synthetic Search', 'Synthetic API', 'api.synthetic.new', 'SYNTHETIC_API_KEY', 'Synthetic quotas'. Do NOT trigger for general browser automation, full-site crawling, or unrelated search providers.
29tweet-replicate
Rebuild a public X/Twitter status into a deterministic local replica with a frozen snapshot, local HTML/CSS, Playwright capture, X-like media-frame fill behavior, a high-quality MP4 master, and a companion GIF capped under 24 MB. Use when asked to replicate a tweet/X post, freeze a status into video, make a tweet look like X offline, or create rerenderable tweet assets with a saved build folder. Trigger on: 'replicate this tweet', 'turn this X post into MP4', 'make this tweet into a GIF too', 'freeze this status locally'. Do NOT use for plain tweet text extraction, raw media download only, live X browser capture, authenticated pages, DMs, or promises of a pixel-perfect private X renderer.
29nanobanana-infographic
Create sleek, low-noise infographics with Nano Banana 2 for blog posts, executive decks, reports, and editorial explainers. Use when the user wants infographic prompt variants, Nano Banana 2 image-generation guidance, or render workflows that avoid clutter, poster energy, and filler. Triggers on: 'infographic', 'Nano Banana 2', 'Gemini image', 'executive visual', 'blog diagram', 'presentation visual'. Do NOT trigger for photorealistic art, mascot illustrations, logo design, meme cards, or raw dashboard screenshots.
29