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 を読む
• [[_TOSP_]]、<details>、query-table、@ メンション、KaTeX、動画の埋め込みなど、Wiki のみで使える機能を使用する -> 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 キーを押す前に、行末に半角スペースを 2 つ追加する
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
サブページ一覧、折りたたみ可能なセクション、クエリテーブル、メンション、KaTeX、動画の埋め込みなど、Wiki のみで使える機能	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

運用ルール

• Mermaid、[[_TOC_]]、[[_TOSP_]]、query-table、HTML タグ、テーブルセル内の <br/>、折りたたみ可能な <details> セクションを安全に使用できる対象として、Wiki ページを扱ってください。PR、README、ウィジェット、Done フィールドでも同じ機能が使えると決めつける前に、references/support-matrix.md を確認してください。
• フローチャート形式の Mermaid では、graph TD または graph LR を推奨します。Microsoft は Mermaid のサポートをドキュメント化していますが、Azure DevOps では flowchart 構文に制限があることも明示しています。
• 提案の意思決定ツリーでは、ノードごとに分岐の質問を 1 つにし、推奨事項、リスク、次のステップは図の下に記載してください。
• bash、powershell、json、yml、ts、tsx、python、csharp、cpp、sql、plaintext など、一般的なコードフェンスのエイリアスを推奨します。特殊なケースやエイリアスの重複には、ヘルパースクリプトを使用してください。
• ユーザーがブラウザーエディターではなくソース管理上で Wiki の Markdown を直接編集する場合は、UI のみを対象とする手順ではなく、文字どおりの構文としてドキュメント化されたものを優先してください。
• マクロ、ソースコードのリテラル、実際のクエリ GUID や ID GUID は正確に保持してください。文章のスタイルを整えるために識別子を作り出したり、コードを修正したりしないでください。テンプレートは構文や有用なレイアウトを示すものです。スターターのセクションを無理に当てはめず、指定されたページ構成に従ってください。

ガイダンスが不十分な場合

制限が古い、不十分、または対象と矛盾する場合は、Microsoft Learn の最新ドキュメントを、Services/Server のバージョンセレクターと関連するリリースノートを使って確認してください。対象でサポートされていることを確認でき、ユーザーの権限内であれば、新たにサポートされた構文を使用してください。上流の Mermaid や Highlight.js で使える機能だけでは、Azure でのサポートの証明にはなりません。ドキュメントを確認できない場合や結論が出ない場合は、その不足を明示し、互換性のある基準または許可されたレンダリング確認を使用してください。情報源、対象のバージョン、最小限のレンダリング例または確認方法を添えて、標準のスキルへの修正を提案してください。通常よく知られた構文について調べたり、インストール済みのコピーを黙って変更したりしないでください。

注意点

1. Azure DevOps では、多くの Markdown レンダラーよりも改行の条件が厳しくなっています。Enter キーを押すだけでは段落内の改行になりません。改行の前に半角スペースを 2 つ追加してください。
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 には、クエリ名やクエリの完全な URL ではなく、実際の Azure Boards クエリ GUID が必要です。
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 ページが正しく表示されることを証明するものではありません。