# 画面設計書 14-Usage-Plugins

## 概要

本ドキュメントは、Prettierドキュメントサイトの「Usage - Plugins」画面の設計書です。この画面はPrettierプラグインの使用方法と開発方法を包括的に説明するドキュメントページです。

### 本画面の処理概要

この画面はPrettierのプラグインシステムについて詳細なガイダンスを提供する静的ドキュメントページです。プラグインの使用方法（CLI、API、設定ファイル経由）、公式プラグイン一覧、コミュニティプラグイン一覧、そしてプラグイン開発のための詳細なAPI仕様を解説しています。

**業務上の目的・背景**：Prettierは多くの言語をビルトインでサポートしていますが、PHP、Ruby、XML、Java等の言語や特殊なフォーマット要件にはプラグインが必要です。この画面は、開発者が既存プラグインを活用する方法と、新しい言語やフォーマットルールをPrettierに追加するためのプラグイン開発方法を提供します。

**画面へのアクセス方法**：ユーザーはメインサイトのナビゲーションバーから「Docs」セクションに入り、サイドバーの「Usage」カテゴリ内の「Plugins」リンクをクリックしてアクセスします。URLは `/docs/plugins` です。

**主要な操作・処理内容**：
1. CLI（`--plugin`オプション）でのプラグイン読み込み方法の理解
2. API（`plugins`オプション）でのプラグイン読み込み方法の理解
3. 設定ファイルでのプラグイン指定方法の理解
4. 公式・コミュニティプラグインの一覧確認
5. プラグイン開発のためのAPI仕様（languages、parsers、printers、options、defaultOptions）の理解

**画面遷移**：この画面からはCLIドキュメント、APIドキュメント、設定ファイルドキュメント、および外部のGitHubリポジトリへのリンクが設定されています。

**権限による表示制御**：なし。全ユーザーが同一のコンテンツを閲覧可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 31 | プラグインローダー | 主機能 | 外部プラグインの読み込み・使用方法を説明 |
| 32 | ビルトインプラグイン管理 | 補助機能 | 組み込みプラグインの仕組みを説明 |
| 33 | カスタムパーサー/プリンター登録 | 補助機能 | カスタムプラグインでのパーサー・プリンター登録を説明 |
| 34 | 行制御（line、softline、hardline） | 補助機能 | プラグイン作成時のDocビルダー使用方法を説明 |
| 35 | インデント制御（indent、dedent、align） | 補助機能 | プラグイン作成時のインデント制御を説明 |
| 36 | グループ化（group、conditionalGroup） | 補助機能 | プラグイン作成時のグループ化機能を説明 |
| 37 | 結合（join、fill） | 補助機能 | プラグイン作成時の結合機能を説明 |
| 38 | 条件分岐（ifBreak） | 補助機能 | プラグイン作成時の条件分岐機能を説明 |
| 39 | Docユーティリティ | 補助機能 | プラグイン作成時のユーティリティ関数を説明 |

## 画面種別

ドキュメント / 参照

## URL/ルーティング

- **URL**: `/docs/plugins`
- **ソースファイル**: `docs/plugins.md`
- **生成方式**: Docusaurus docs機能によるMarkdownからの静的HTML生成

## 入出力項目

本画面は静的ドキュメントページのため、ユーザー入力フィールドはありません。

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| Using Plugins | プラグイン使用方法 | CLI、API、設定ファイル経由での読み込み |
| Official Plugins | 公式プラグイン一覧 | @prettier/plugin-php, ruby, xml, pug |
| Community Plugins | コミュニティプラグイン一覧 | 約25のサードパーティプラグイン |
| Developing Plugins | プラグイン開発ガイド | 5つのエクスポート仕様 |
| languages | 言語定義 | 対応言語の定義方法 |
| parsers | パーサー定義 | ASTへの変換処理の定義 |
| printers | プリンター定義 | Doc生成処理の定義 |
| options | オプション定義 | カスタムオプションの追加方法 |
| defaultOptions | デフォルトオプション | コアオプションのデフォルト値変更 |
| Utility functions | ユーティリティ関数 | prettier.utilで提供される関数一覧 |
| Testing Plugins | テスト方法 | プラグインのテスト実行方法 |

## イベント仕様

### 1-外部リンククリック

ドキュメント内の外部リンクをクリックすると、対応するGitHubリポジトリに遷移します。

- 公式プラグインリポジトリへのリンク
- コミュニティプラグインリポジトリへのリンク
- Docビルダーコマンドドキュメントへのリンク

### 2-内部リンククリック

- `cli.md` → CLIドキュメント
- `api.md` → APIドキュメント
- `configuration.md` → 設定ファイルドキュメント
- `options.md` → オプションドキュメント

## データベース更新仕様

本画面は静的ドキュメントページのため、データベース更新は発生しません。

## メッセージ仕様

本画面は静的ドキュメントページのため、動的メッセージはありません。

## 例外処理

| 状態 | 説明 |
|------|------|
| ページ未発見（404） | URLが誤っている場合、Docusaurus標準の404ページを表示 |
| 外部リンク切れ | 外部リポジトリのURLが変更された場合、ユーザーに404表示 |

## 備考

- このドキュメントはPrettier v3.0.0以降のプラグインAPIを説明（Custom Parser APIは削除）
- `embed`メソッドの非同期対応について詳細な説明あり
- `printPrettierIgnored`はv3.7.0で追加された機能
- `canAttachComment`の第2引数`ancestors`はv3.7.0で追加
- TypeScript型定義（`AstPath`, `Options`, `Doc`等）が使用されている

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: ドキュメントコンテンツを理解する

本画面のコンテンツはMarkdownファイルで管理されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | plugins.md | `docs/plugins.md` | プラグインAPI全体像を理解 |

**読解のコツ**: 大規模なドキュメントのため、Using Plugins → Official Plugins → Developing Pluginsの順で読み進めることを推奨。

#### Step 2: プラグインローダーの実装を理解する

プラグインの読み込み処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | support.js | `src/main/support.js` | getSupportInfo関数でのプラグイン統合 |
| 2-2 | parser-and-printer.js | `src/main/parser-and-printer.js` | パーサー・プリンター解決処理 |

**主要処理フロー**:
1. プラグインからlanguages、parsers、printersを抽出
2. コアの言語定義とマージ

#### Step 3: Docビルダーの実装を理解する

プラグイン開発で使用するDocビルダーを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/document/index.js` | Docビルダーのエクスポート |
| 3-2 | builders.js | `src/document/builders.js` | line, softline, hardline等の実装 |

**主要処理フロー**:
- Docビルダー関数（group, indent, join等）の定義

#### Step 4: ユーティリティ関数の実装を理解する

prettier.utilで提供される関数を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.js | `src/index.js` | utilエクスポートの確認 |

### プログラム呼び出し階層図

```
prettier.format(code, { plugins: [...] })
    │
    ├─ normalizeOptions
    │      └─ プラグインからオプション定義を抽出
    │
    ├─ resolveParser
    │      └─ プラグインからパーサーを検索
    │             └─ parser.parse(text, options)
    │
    └─ resolvePrinter
           └─ プラグインからプリンターを検索
                  └─ printer.print(path, options, print)
                         └─ Doc生成
```

### データフロー図

```
[入力]                          [処理]                        [出力]

プラグイン定義 ────────────▶ Plugin Loader ────────────▶ 統合された言語定義
{                                   │
  languages: [...],                 ├─ languages抽出
  parsers: {...},                   ├─ parsers抽出
  printers: {...},                  └─ printers抽出
  options: {...}
}
        │
        ▼
ソースコード ────────────▶ parser.parse() ────────────▶ AST
                                                         │
                                                         ▼
                          printer.print() ◀─────────────┘
                                 │
                                 ▼
                              Doc (IR)
                                 │
                                 ▼
                          printDocToString()
                                 │
                                 ▼
                          フォーマット済みコード
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| plugins.md | `docs/plugins.md` | ドキュメント | プラグインガイド |
| support.js | `src/main/support.js` | ソース | プラグイン統合処理 |
| parser-and-printer.js | `src/main/parser-and-printer.js` | ソース | パーサー/プリンター解決 |
| index.js | `src/document/index.js` | ソース | Docビルダーエクスポート |
| builders.js | `src/document/builders.js` | ソース | Docビルダー実装 |
| cli.md | `docs/cli.md` | ドキュメント | CLIオプションドキュメント（関連参照） |
| api.md | `docs/api.md` | ドキュメント | APIドキュメント（関連参照） |
| configuration.md | `docs/configuration.md` | ドキュメント | 設定ファイルドキュメント（関連参照） |
