はじめに
DevOps 編の 2 回目は、Azure DevOps の Wiki とドキュメント。
Wiki の 2 つの種類(プロジェクト Wiki とコード Wiki)、使える Markdown、中身が Git であることを押さえたうえで、実際に Wiki を作り、git で編集し、ドキュメントのフォルダーを Wiki として公開し、ブランチ ポリシーで保護するところまで試す。
※2026年11月時点の情報です。
前回:Azure Boards とは

Wiki、README、Markdown の全体像
Azure DevOps では、プロジェクトの情報を Markdown で書いて共有する。
書く場所は、プロジェクト Wiki、コード Wiki、リポジトリやプロジェクトの README、ダッシュボードの Markdown ウィジェット。
Wiki は 2 種類あり、どちらも中身は Git リポジトリに置かれた Markdown ファイル。

| 項目 | プロジェクト Wiki | コード Wiki |
|---|---|---|
| 作り方 | Wiki の画面で「Create project wiki」 | Wiki の画面で「Publish code as wiki」。 リポジトリ、ブランチ、フォルダーを選ぶ |
| 置き場所 | 専用のリポジトリ(<プロジェクト名>.wiki) | 既存のリポジトリの中のフォルダー |
| 編集 | Wiki の画面で追加・編集する。git clone して手元で編集してもよい | リポジトリのファイルとして編集する(Wiki の画面からはリポジトリでの編集に進む) |
| 向いているもの | チームの手順、議事録、ナレッジ | コードと一緒にバージョン管理したい設計書や API の説明。 プル要求でレビューしてから反映できる |
GitHub にも README と Wiki がある。
GitHub の README はリポジトリを開いた人が最初に見るもので、Wiki は長いドキュメント向け。
GitHub の Wiki も Markdown で書け、Mermaid などの図や数式を入れられる。
| 項目 | Azure DevOps | GitHub |
|---|---|---|
| README | リポジトリごと、プロジェクトごとに置ける | .github、ルート、docs の順に探して表示する。 500 KiB を超える部分は切り捨て |
| Wiki | プロジェクト Wiki とコード Wiki | リポジトリごとの Wiki。 ファイル数 5,000 のソフト制限があり、大きいものは GitHub Pages を勧めている |
| 図 | Mermaid(::: mermaid と “`mermaid の 2 つの書き方) | Mermaid、GeoJSON、TopoJSON、ASCII STL |
公式ドキュメント:
Wiki、README、Markdown について | Microsoft Learn
プロビジョニングされた Wiki とコード Wiki として発行された Wiki | Microsoft Learn
リポジトリの README ファイルについて – GitHub Docs
ウィキについて – GitHub Docs
ダイアグラムの作成 – GitHub Docs
Markdown で使えるもの
Azure DevOps の Wiki では、標準の Markdown に加えて次のものが使える。
| 機能 | 書き方 | ポイント |
|---|---|---|
| 目次 | [[_TOC_]] | ページの見出しから目次を作る |
| Mermaid の図 | ::: mermaid で始めて ::: で閉じる(または “`mermaid のコード ブロック) | フローチャート、シーケンス図、ガント チャートなど |
| 数式 | $…$(インライン)、$$…$$(ブロック) | KaTeX の記法 |
| 作業項目へのリンク | # と作業項目の ID | 入力すると候補が出て、選ぶと作業項目のカードとして表示される。 色コードなどで # を使うときは \# にする |
| 機能 | 書き方 | ポイント |
|---|---|---|
| メンション | @ と人やグループ | ユーザーやグループをメンションする |
| 折りたたみ | <details> と <summary> | HTML のタグでセクションを折りたためる |
| 添付 | 画像やファイルを添付し、リンクで参照する | 添付は .attachments フォルダーに置かれる |
[[_TOC_]]
## 構成
::: mermaid
graph LR
U[利用者] --> W[Web]
W --> A[検索 API]
A --> D[(DB)]
:::
## 関連する作業項目
- 決済 #5
数式:$c = \sqrt{a^2 + b^2}$

公式ドキュメント:Azure DevOpsで Markdown を使用する | Microsoft Learn
Wiki の中身は Git
Wiki のページは、Git リポジトリの中の Markdown ファイルとして保存される。
Wiki の画面で編集しても、git clone して手元で編集して push しても同じリポジトリが変わる。
| ファイル・フォルダー | 役割 |
|---|---|
| ページ名.md | 1 ページ 1 ファイル。 ファイル名がページのタイトルになる(ファイル名のハイフンはタイトルでは空白になる) |
| ページ名のフォルダー | サブページを入れる。フォルダー名は親のページ名と同じ |
| .order | そのフォルダーのページの並び順。1 行に 1 ページ名 |
| .attachments | Wiki で使う添付ファイル |
| ファイル・フォルダー | 役割 |
|---|---|
| ブランチ | プロジェクト Wiki のリポジトリの既定ブランチ(公式の説明では wikiMain)。 ほかのリポジトリと同じようにブランチ ポリシーを付けられる |
| 制限 | 内容 |
|---|---|
| ページのファイル | 最大 18 MB |
| 添付ファイル | 最大 19 MB |
| ファイル名 | スラッシュ(/)、バックスラッシュ(\)、ハッシュ(#)は使えない。 先頭と末尾にピリオドは置けない |
公式ドキュメント:
Git の Wiki ファイルとフォルダー構造 | Microsoft Learn
Wiki コンテンツをオフラインで複製および更新する | Microsoft Learn
Wiki ページの追加と編集 | Microsoft Learn
アクセス許可と検索
Wiki の権限は、中身を置いている Git リポジトリのセキュリティで決まる。
既定では、共同作成者(Contributors)のメンバーが Wiki を読み書きできる。
| 操作 | 既定で許可されている人 |
|---|---|
| プロジェクト Wiki を見る | 利害関係者、閲覧者、共同作成者、チーム管理者、プロジェクト管理者 |
| Wiki を作る(プロビジョニング) | プロジェクト管理者 |
| Wiki のページを編集する | 共同作成者(基になるリポジトリへの書き込み権限) |
Wiki の検索では、プロジェクト Wiki とコード Wiki をまとめて探せる。
作ったばかりの Wiki は、索引ができるまで検索結果に出ない。
公式ドキュメント:
Wiki とコラボレーション ツールのアクセス許可を管理する | Microsoft Learn
検索の使用を開始する | Microsoft Learn
やってみる
今回の構成と実施すること

| 手順 | 実施すること | 確かめること |
|---|---|---|
| ① | プロジェクト Wiki を作り、ホームに目次、Mermaid、数式、作業項目のリンクを書く | Markdown がどう表示されるか |
| ② | git clone してページ、サブページ、.order、添付を足し、push する | 手元の変更が Wiki の画面に反映されるか |
| ③ | リポジトリの docs フォルダーをコード Wiki として公開する | ブランチ選択付きの Wiki になる |
| ④ | Wiki を検索する | 2 つの Wiki がまとめて検索される |
| 手順 | 実施すること | 確かめること |
|---|---|---|
| ⑤ | Wiki のブランチにブランチ ポリシーを付ける | git push と Wiki 画面の保存が止まる |
① プロジェクト Wiki を作る
プロジェクトの「Overview」⇒「Wiki」を開く。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | Create project wiki / Publish code as wiki | プロジェクト Wiki を作るか、リポジトリのフォルダーをコード Wiki として公開するか |
「Create project wiki」を選ぶとエディターが開く。
左に Markdown、右にプレビューが出る。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | ツール バー | 書式、リンク、表、作業項目(#)、添付、Mermaid の図の挿入など |
| 2 | 目次 | [[_TOC_]] で見出しの一覧ができる |
| 3 | Mermaid | プレビューでは「Load diagram」で図を読み込む |
保存したページを表示した。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | 目次 | 見出しへのリンクになる |
| 2 | #4、#6 | 全角の「:」の直後に書いたので、作業項目へのリンクにならなかった(実機でつまずいた点を参照) |
| 3 | Mermaid の図 | graph LR で書いた流れが図になった |
| 4 | 数式 | \text{…} の中に日本語を入れたため、描画されずに文字のまま出た |
② git clone して手元で編集する
Wiki のリポジトリを git clone すると、ブランチは wikiMaster で、中身は .gitignore、.order(中身は「ホーム」)、ホーム.md だった。
公式の説明では既定のブランチは wikiMain となっているが、今回作った Wiki では wikiMaster だった。
運用手順.md、サブページ用の 運用手順 フォルダーと 障害対応.md、それぞれの .order、.attachments の画像を足して push した。
git clone https://dev.azure.com/<組織>/<プロジェクト>/_git/<プロジェクト>.wiki
cd <プロジェクト>.wiki
git branch # * wikiMaster
# ページとサブページ、並び順、添付を追加
# 運用手順.md
# 運用手順/障害対応.md
# .order(ホーム、運用手順)と 運用手順/.order(障害対応)
# .attachments/board-setup.png
git add -A
git commit -m "運用手順のページを追加"
git push origin wikiMaster

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | ページのツリー | .order の順に「ホーム」「運用手順」が並び、運用手順の下に「障害対応」が入った |
| 2 | #7 | これも全角の「:」の直後なのでリンクにならなかった |
| 3 | 数式 | 英数字だけの数式は、インラインもブロックも描画された |
Wiki の画面で、半角スペースのあとに # と番号を入れると、作業項目の候補が出た。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | 候補 | 「User Story 5: クレジットカードで支払える」が出る |
| 2 | プレビュー | 作業項目の番号、タイトル、状態のカードとして表示される |
※作業項目の側の「リンク」(関係)には、この Wiki ページは追加されなかった(REST API で確認)。
添付の画像は、Markdown から /.attachments/ のパスで参照すると表示された。

③ docs フォルダーをコード Wiki として公開する
リポジトリ boards-demo に README.md と docs フォルダー(はじめに.md、api.md、api/検索.md)を push した。
Wiki の一覧のメニューから「Publish code as wiki」を選ぶ。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | Repository | 公開するリポジトリ |
| 2 | Branch | 公開するブランチ(今回は main) |
| 3 | Folder | Wiki にするフォルダー(今回は /docs) |
| 4 | Wiki name | Wiki の名前(今回は boards-demo-docs) |

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | ブランチ | コード Wiki にはブランチの選択欄が付く |
| 2 | ページ | .order を置いていないので、ファイル名の順(api > 検索、はじめに)に並んだ |
④ Wiki を検索する
Wiki を作った直後は、索引の作成中で結果が出なかった。

Wiki を作ってから 8 分ほどで、検索の結果が出た。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | 結果 | プロジェクト Wiki の 運用手順 > 障害対応.md が見つかった |

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | コード Wiki | boards-demo-docs の docs/api.md |
| 2 | プロジェクト Wiki | boards-demo.wiki のホーム.md。 2 つの Wiki がまとめて検索された |
⑤ Wiki のブランチを保護する
Wiki のリポジトリはリポジトリの一覧には出ないが、ブランチの画面は URL(_git/<プロジェクト>.wiki/branches)で開けた。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | wikiMaster | 既定(Default)のブランチ |
行のメニューの「Branch policies」はプロジェクト設定のリポジトリの一覧に進むだけで、Wiki のリポジトリは一覧になかった。
そこで、REST API で wikiMaster に「最小レビュー担当者数 1」のポリシーを付けた。
この状態で手元から push すると、拒否された。
! [remote rejected] wikiMaster -> wikiMaster (TF402455: Pushes to this branch are not permitted; you must use a pull request to update this branch.)
Wiki の画面でページを直して保存しても、止められた。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | メッセージ | 「Pushes to this branch is not permitted. Please continue with ‘Edit in Repos’ and use a pull request to update this branch.」 |
ブランチ ポリシーを付けると、Wiki の画面からも直接は書けず、プル要求での更新が必要になる。
なお、Wiki を作ったときに、Wiki のリポジトリには「ファイル サイズの制限」(25 MiB、超えると拒否)のポリシーが自動で付いていた(REST API で確認)。
実機でつまずいた点
#番号が作業項目のリンクにならない
「検索:#4」のように、全角の「:」の直後に # と番号を書くと、作業項目のリンクにならず、ただの文字のまま表示された。
エディターでも、全角の文字の直後では作業項目の候補が出なかった。
# の前に半角スペースを入れると候補が出て、作業項目のカードとして表示された。
日本語の文の中で作業項目を参照するときは、# の前に半角スペースを入れる。

数式の \text に日本語を入れると描画されない
$\text{月額} = \text{時間単価} \times 730$ のように \text の中に日本語を入れた数式は、描画されずに記号のまま表示された。
同じページでも、英数字だけの数式($c = \sqrt{a^2 + b^2}$ など)は描画された。
数式の中は英数字にし、日本語の説明は数式の外に書く。

We are not able to show results because one or more projects in your organization are still being indexed
Wiki を作った直後に検索すると、このメッセージが出て結果が 0 件だった。
画面には「2 時間たっても結果が出なければ連絡を」と出ていて、今回は Wiki を作ってから 8 分ほどで検索できるようになった。
新しい Wiki やプロジェクトは、しばらくしてから検索する。

推奨構成
| 項目 | 推奨 |
|---|---|
| 使い分け | チームの手順やナレッジはプロジェクト Wiki、コードと一緒に版を管理したい設計書や API の説明はコード Wiki |
| レビュー | 大事な Wiki はブランチ ポリシーで保護し、プル要求で更新する |
| 構成 | .order で並び順を決め、添付は .attachments に置く。 サブページはフォルダーで分ける |
| 書き方 | 目次と Mermaid の図を使う。 作業項目は # の前に半角スペースを入れてリンクする |
注意事項
| 項目 | 内容 |
|---|---|
| ブランチ名 | 公式の説明は wikiMain だが、今回作った Wiki は wikiMaster だった。 git で扱う前にブランチ名を確かめる |
| サイズ | ページのファイルは最大 18 MB、添付は最大 19 MB |
| Wiki のリポジトリ | リポジトリの一覧に出ないため、ブランチ ポリシーはポータルから設定できなかった(REST API で設定した) |
| 権限 | Wiki の権限は基になる Git リポジトリのセキュリティで決まる |
| 項目 | 内容 |
|---|---|
| 検索 | 作った直後は索引の作成中で結果が出ない |
| 数式 | \text の中の日本語は描画されなかった |
公式ドキュメント:
Git の Wiki ファイルとフォルダー構造 | Microsoft Learn
Wiki ページの追加と編集 | Microsoft Learn
Wiki とコラボレーション ツールのアクセス許可を管理する | Microsoft Learn
まとめ
・Azure DevOps の Wiki は、専用リポジトリのプロジェクト Wiki と、リポジトリのフォルダーを公開するコード Wiki の 2 種類で、どちらも中身は Git の Markdown。
・Markdown では目次、Mermaid、数式、作業項目のリンク、折りたたみ、添付が使え、作業項目のリンクは # の前に半角スペースが要った。
・git clone して .order や .attachments を含めて編集でき、プロジェクト Wiki の既定のブランチは wikiMaster だった。
・Wiki のブランチにポリシーを付けると、git push も Wiki 画面の保存も止まり、プル要求での更新になる。
次回:Azure Repos と Git




コメント