format-docs

ドキュメントのフォーマット

orbit confluence publish を使って Confluence にきれいに公開できるよう、Markdown ドキュメントを整えます。このスキルでは、Confluence が想定する規約に従って、Markdown ファイルを個別またはディレクトリツリー全体で分析・変換します。

使用するタイミング

• ドキュメントディレクトリで初めて orbit confluence publish を実行する前
• 公開済みのドキュメントツリーに新しい Markdown ファイルを追加するとき
• Confluence でドキュメントの表示が崩れ、構造上の修正が必要なとき
• 別のシステム（GitHub wiki、Notion のエクスポートなど）からドキュメントを移行するとき

プロセス

1. 対象範囲の確認

ユーザーが単一のファイルとディレクトリのどちらについて依頼しているかを判断します。

• 単一ファイル：ファイルを読み込み、以下のファイル単位のチェックを適用します。
• ディレクトリ：ツリー全体を一覧表示し、ディレクトリ単位とファイル単位の両方のチェックを行います。

2. ディレクトリ単位のチェック

ディレクトリをフォーマットする場合は、次の構造上の問題を確認して修正します。

INDEX.md ファイル — Markdown ファイルを含む各ディレクトリには、INDEX.md が必要です。このファイルは、Confluence で同じ階層にあるすべての .md ファイルの親ページになります。

docs/
  INDEX.md              ← Required: parent page for docs/
  overview.md
  api/
    INDEX.md            ← Required: parent page for api/
    endpoints.md

INDEX.md がない場合は、次の内容を含むファイルを作成します。

• フロントマター（ディレクトリ名をタイトルにし、今日の日付を指定）
• 簡潔な紹介文
• プロパティレポートディレクティブ（下記参照）
• Confluence ignore ブロックで囲んだ子ページのテーブル

INDEX.md の構造 — 各 INDEX.md は次のパターンに従う必要があります。

---
title: "Section Title"
# ... full frontmatter ...
confluence_labels:
  - my-label
---

# Section Title

> Brief intro summarizing the section.

---





## Subsection Name

| Document | Version | Summary |
|----------|---------|---------|
| [Child Page](./child-page.md) | v1.0 | Brief description |

INDEX.md ファイルに関する主なルール：

1. プロパティレポートディレクティブ — 紹介文の後に `` ディレクティブを追加します。これにより、同じラベルを持つすべての子ページからメタデータを取得する動的なテーブルが Confluence に生成されます。子ページに対象を絞るには ancestor = currentContent() を使用し、confluence_labels のラベルに一致させます。
2. Confluence ignore ブロック — 子ページの一覧を記載するすべてのコンテンツ（セクション見出し、テーブル、リンク）を と の間に配置します。このコンテンツは Markdown ビューア（GitHub、ローカル）でのみ表示され、Confluence ではプロパティレポートに置き換えられます。
3. ラベルの一致 — CQL クエリの label 値は、子ページのフロントマターで定義されている confluence_labels と一致させる必要があります。レポートにすべての兄弟ページを含めるため、同じ階層のページでは同じラベルを使用します。
4. レポートの見出し — 最低限、Owner,Status,Version,Reviewed on を含めます。これらは子ページの confluence_properties にあるフィールド名と一致させる必要があります。

ファイル名 — URL の問題につながるファイル名を変更します。

• 小文字とハイフンを使用します。API Reference.md ではなく api-reference.md とします。
• ファイル名にスペース、アンダースコア、特殊文字を使用しません。
• ファイル名にバージョン番号を含めません。バージョンは代わりにフロントマターで管理します。

フラットな階層 — Confluence のページツリーは、ルート直下にトピックディレクトリが 1 階層ある構成が最適です。ディレクトリに深くネストされたサブディレクトリ（3 階層以上）がある場合は、階層を浅くすることを提案します。

3. ファイル単位のチェック

各 Markdown ファイルについて、次の項目を確認して修正します。各項目の詳細なルールについては、フォーマットのリファレンスを参照してください。

Frontmatter

すべてのファイルに、すべての標準フィールドが入力された YAML frontmatter が必要です。Frontmatter はドキュメントのメタデータの唯一の信頼できる情報源です。frontmatter に存在するメタデータは、ドキュメント本文に重複して記載しないでください。

必ず完全な frontmatter テンプレートを使用してください：

---
title: API Reference
subtitle: "Reference — Project Docs v1.0"
date: "2026-03-09"
author: "Engineering Team"
confluence_ignore: false
confluence_labels:
  - api
  - reference
confluence_properties:
  - id: status
    fields:
      Owner: "Engineering Team"
      Classification: Internal
      Status: "{status:Green|Published}"
      Version: v1.0
      Reviewed on: 2026-03-05
---

frontmatter を追加または補完する場合：

• title は、最初の # heading がある場合はそこから、ない場合はファイル名から導出します
• date は今日の日付に設定します
• author は、インラインメタデータがある場合はそこから、ない場合は既存の同階層ファイルから導出するか、ユーザーに尋ねます
• subtitle は、ドキュメントの文脈から導出します（例："ADR — Project v1.0"、"Guide — Team Docs"）
• ディレクトリ名と内容に基づいて confluence_labels を提案します
• 必ず confluence_properties を含めてください。最低限、Owner、Classification、Status、Version、Reviewed on を含めます
• ドキュメント本文にインラインメタデータがある場合は、そこからプロパティ値を設定します
• デフォルトで confluence_ignore: false に設定します。ファイルを Confluence への公開対象から除外するようユーザーが明示的に希望した場合にのみ true に設定します（以前公開されたページは次回の同期時に削除されます）
• 既存の confluence_page_id や confluence_url は上書きしないでください

重複するインラインメタデータの削除

frontmatter を入力した後、frontmatter または confluence_properties にすでに記録された情報と重複するインラインメタデータブロックをすべてドキュメント本文から削除します。こうしたブロックは通常、ドキュメント上部に太字のキーと値の行、または小さな表として記載されています。

検出して削除するパターン：

**Document Version**: 1.0
**Status**: Draft (Proposal)
**Classification**: Internal
**Last Updated**: March 7, 2026
**Author**: Engineering Team
**Owner**: Platform Team

次の形式で記載されたメタデータも検出して削除します：

• キーと値の行：Version: 1.0 または Status: Draft
• メタデータらしい見出しがある小さな2列の表（例：| Field | Value |）
• 引用形式のメタデータ：> **Version**: 1.0

削除ルール：

• 情報がfrontmatterフィールドまたは confluence_properties フィールドにすでに記録されているメタデータの行またはブロックのみ削除します
• インラインメタデータブロックにfrontmatterに未記載の値が含まれている場合は、その値を先にfrontmatterに取り込んでからブロックを削除します
• 周囲のコンテンツは保持し、メタデータの行のみ削除します
• メタデータブロックの後に空行または水平線が続く場合は、余分な空白が残らないよう区切りも削除します

見出しの階層

コンバーターは最初の # heading をスキップします（Confluence ではページタイトルが使用されます）。そのため、ドキュメント本文では ## を最上位のセクション見出しとして使用してください。

次の問題を修正します：

• 複数の # 見出し — 最初の見出しのみ残します（これがタイトルになります）。それ以降の # は ## に変換します
• 見出しの階層の飛び越し — ## から #### に飛ばさないでください。階層を補います
• # 見出しがない場合 — ファイルに # 見出しがなく、frontmatter に title があれば問題ありません。どちらもない場合は、ファイル名から導出した # 見出しを追加します

ドキュメント構成

構成の整ったドキュメントは、次のパターンに従います：

# Title

> One-line summary of what this document covers.



## Table of Contents

1. [Section One](#section-one)
2. [Section Two](#section-two)



---

## Section One

Content...

---

## Section Two

Content...

次の構成上の改善を適用します：

• ドキュメントに ## 見出しのセクションが3つ以上ある場合は、目次を追加します。目次セクション（見出しとリスト）は / ディレクティブで囲み、公開時に Confluence の目次マクロに置き換えられるようにします。Markdown の目次は GitHub やローカルのレンダラーでは引き続き表示されます
• 視覚的に区切れるよう、主要なセクション間に水平線（---）を追加します
• タイトルの直後に文脈の説明がなく、いきなり本文が始まる場合は、要約の引用ブロックを追加します

相互参照

ファイルがフォーマット対象のディレクトリに含まれる場合は、下部に関連する同階層のドキュメントへのリンクを含む「相互参照」セクションを追加します：

## Cross-References

| Document | Relevance |
|----------|-----------|
| [Related Doc](./related-doc.md) | Brief note on why it's relevant |

ローカル環境と Confluence の両方でリンクが正しく解決されるよう、相対パスを使用してください。

改訂履歴

継続的に保守されるドキュメントには、末尾に改訂履歴の表を追加します：

## Revision History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2026-03-09 | Initial document |

すでに改訂履歴がある場合は追加しないでください。

4. コンテンツの書式設定

Confluence で正しく変換されない Markdown のパターンを修正します。

問題	修正
インラインのメタデータブロック（**Status**: Draft など）	frontmatter／confluence_properties に取り込み、本文から削除します
生の HTML タグ	Markdown の同等の記法に置き換えます
<br> タグ	代わりに空行を使います
深くネストしたリスト（3 階層以上）	最大 2 階層にフラット化します
複数行のセルがある表	よりシンプルな表に分割します
相対パスを使ったインライン画像	ファイルからの相対パスが正しいことを確認します
GitHub 形式のアラート（> [!NOTE]）	そのままにします。コンバーターが処理します
MkDocs の警告記法（!!! note）	そのままにします。コンバーターが処理します

5. 図の書式設定

図の言語（mermaid、plantuml、graphviz、d2 など）を使ったフェンス付きコードブロックは、Confluence への公開時に Kroki を介して PNG 画像としてレンダリングされます（公開サービスの https://kroki.io、またはプロファイルで指定したセルフホストのインスタンス）。Orbit はよくある問題を自動で修正しますが、最良の結果を得るには、図のソースで以下のルールに従ってください。

これはデフォルトの設定です（--diagrams kroki）。ほかに 2 つの方式があり、以下のルールの適用範囲が異なります。

方式	図のブロックの処理
kroki（デフォルト）	すべての図の言語を、設定された Kroki インスタンスから PNG として出力します。以下の自動修正が適用されます。
markdown-macro	Mermaid を Confluence の markdown マクロに変換し、閲覧者のブラウザー上で動的に描画します。それ以外の言語はすべてコードブロックのままです。Kroki には接続しません。
code-block	すべての図を整形済みテキストのままにします。ネットワーク接続は行いません。

markdown-macro では以下の自動修正は適用されません。これらは Kroki がレンダリングする Mermaid のビルドに対応するためのもので、マクロのアプリは独自の設定（htmlLabels: true）でレンダリングするため、ラベル内の <br/> は削除対象ではなく改行になります。後述する手動修正は引き続き適用されます。これらは Kroki 固有ではなく、正しい図を記述するためのものです。

orbit による自動修正（手動での対応は不要、kroki 方式のみ）：

• 参加者名、ノート、メッセージ内の <br/> タグ → 削除
• 参加者エイリアス末尾の括弧付き接尾辞：Worker (queue) → Worker - queue
• 参加者名末尾の () → 削除
• コロンの後にあるポート番号：API:8000 → API
• 逆向きの矢印：Client<<--API: msg → API-->>Client: msg

ドキュメントの書式設定時に手動で修正する必要があるもの：

問題	修正
ASCII の罫線文字（┌┐└┘│─）	正しい Mermaid／D2／PlantUML の構文に変換します
ASCII のシーケンス図（|-- ->）	適切な矢印を使った sequenceDiagram に変換します
図のような内容なのに言語タグがないコードブロック	mermaid、d2、または plantuml の言語タグを追加します
テキストで記述された状態遷移（DRAFT → ACTIVE → DEPRECATED）	stateDiagram-v2 に変換します
非常に大きな図（参加者 15 人以上、メッセージ 50 件以上）	小さな図に分割します

図の種類の選択：

内容	最適な形式
リクエスト／レスポンスのフロー	mermaid sequenceDiagram
状態機械	mermaid stateDiagram-v2
シンプルなフローチャート	mermaid flowchart TD/LR
コンポーネントツリー	mermaid graph TD
エンティティ／データモデル	mermaid erDiagram
ネストしたアーキテクチャ	d2
レイヤー化されたシステム	d2

書式設定対象のドキュメントに ASCII アートやテキスト形式の図がある場合は、適切な図の言語に変換してください。確実に変換できないほど複雑な図は、言語タグに text を指定したプレーンなコードブロックのままにしてください。

6. Confluence 固有の拡張機能

Confluence の機能を活用する任意の改善項目です。

• ステータスバッジ — プロパティフィールドでは {status:Color|Text} 構文を使用します（例：{status:Green|Published}）。絵文字のショートコード（:green_circle: Green）もサポートされています。
• Confluence の無視ブロック — Markdown にのみ表示し、Confluence には表示しないセクションは、と で囲みます。INDEX.md ファイルでは、すべての子ページのテーブルを囲む必要があります（上記の「ディレクトリレベルのチェック」を参照）。
• プロパティレポート — すべての INDEX.md にプロパティレポートのディレクティブを含める必要があります。正確なパターンについては、「ディレクトリレベルのチェック」の INDEX.md の構成を参照してください。

7. ドライラン

変更を加えた後、ユーザーに次のコマンドで確認するよう提案します。

orbit confluence publish <directory> --space <SPACE> --parent <PAGE_ID> --dry-run -p <profile>

これにより、変更を加えずに公開内容をプレビューできます。

ルール

• コンテンツを削除しないでください。構成の変更とメタデータの追加のみ行います。
• confluence_page_id や confluence_url を上書きしないでください。これらは orbit confluence publish によって管理されます。
• 既存のフロントマターのフィールドを保持してください。不足しているフィールドを追加し、既存のフィールドは削除しないでください。
• タイトルに迷った場合は、まず # heading から判断し、次にファイル名から判断してください。
• 変更は最小限に抑えてください。文章を書き直したり、見出しの階層が崩れている場合を除き、セクションを再編成したりしないでください。
• 大きなディレクトリに変更を適用する前に、変更内容の概要をユーザーに提示してください。