# 機能設計書 71-ドキュメンテーション

## 概要

本ドキュメントは、Actual Budgetのドキュメンテーション機能について記述する機能設計書である。Docusaurusフレームワークをベースとした静的サイト生成システムにより、ユーザー向けドキュメントおよび開発者向け情報を提供する。

### 本機能の処理概要

ドキュメンテーション機能は、Actual Budgetプロジェクトの公式ドキュメントサイトを生成・公開するための機能である。ユーザーガイド、インストール手順、API仕様、開発者向けドキュメントなど、包括的な情報を提供する。

**業務上の目的・背景**：オープンソースプロジェクトにおいて、適切なドキュメンテーションはユーザーの導入・利用を促進し、コミュニティへの貢献を容易にするために不可欠である。ユーザーがActual Budgetを効果的に使いこなすための学習リソースを提供し、開発者がプロジェクトに貢献しやすい環境を整備することを目的とする。

**機能の利用シーン**：
- 新規ユーザーがActual Budgetを初めてインストール・設定する際のガイドとして参照
- 既存ユーザーが特定機能の使い方を調べる際のリファレンスとして利用
- 開発者がプロジェクトに貢献する際のコントリビューションガイドとして参照
- 各リリースの変更内容を確認するリリースノートとしてのブログ記事閲覧

**主要な処理内容**：
1. Markdownファイルの解析とHTML変換処理
2. サイドバー構造の生成とナビゲーション構築
3. React/JSXコンポーネントのレンダリング
4. 静的サイトのビルドと最適化
5. 検索インデックスの生成（ローカルサーチ）
6. Mermaid図表のレンダリング
7. 画像の最適化（IdealImage プラグイン）
8. RSSフィードの生成（ブログ機能）

**関連システム・外部連携**：
- GitHub（ソースコード管理、Issue/PRリンク）
- Netlify（ホスティング・デプロイ）
- Open Collective（寄付リンク）
- Discord（コミュニティサポートリンク）
- PikaPods（クイックセットアップリンク）

**権限による制御**：本機能は公開ドキュメントサイトであり、特別な権限制御は行わない。誰でもドキュメントを閲覧可能。ドキュメント編集はGitHubリポジトリへのコントリビューションを通じて行う。

## 関連画面

本機能は独立したドキュメントサイトであり、Actual Budgetアプリケーション内の画面とは直接関連しない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | ドキュメントホーム画面 | 主画面 | ドキュメントサイトのトップページ表示 |
| - | ドキュメント閲覧画面 | 主画面 | 各種ドキュメントの表示・ナビゲーション |
| - | ブログ一覧画面 | 主画面 | リリースノート・ブログ記事一覧表示 |
| - | ダウンロード画面 | 補助画面 | デスクトップアプリダウンロードリンク提供 |

## 機能種別

- 静的サイト生成（SSG）
- コンテンツ管理
- 検索機能
- RSSフィード生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Markdownファイル | .md / .mdx | Yes | ドキュメントコンテンツ | Front Matter形式準拠 |
| JSXコンポーネント | .jsx / .tsx | No | カスタムページ・コンポーネント | React構文準拠 |
| 設定ファイル | .js | Yes | Docusaurus設定 | docusaurus.config.js形式 |
| サイドバー定義 | .js | Yes | ナビゲーション構造 | docs-sidebar.js形式 |

### 入力データソース

- `packages/docs/docs/` - ドキュメントMarkdownファイル
- `packages/docs/blog/` - ブログ記事Markdownファイル
- `packages/docs/src/pages/` - カスタムページ（JSX/MDX）
- `packages/docs/src/components/` - 再利用可能コンポーネント
- `packages/docs/static/` - 静的アセット（画像、ファイル）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| HTMLファイル | .html | レンダリングされたドキュメントページ |
| CSSファイル | .css | スタイルシート |
| JSファイル | .js | クライアントサイドJavaScript |
| 検索インデックス | .json | ローカル検索用インデックス |
| RSSフィード | .xml | ブログRSSフィード |
| 最適化画像 | .webp / .png | 圧縮・リサイズされた画像 |

### 出力先

- `packages/docs/build/` - ビルド成果物ディレクトリ
- Netlify（本番環境 https://actualbudget.org/）

## 処理フロー

### 処理シーケンス

```
1. 設定ファイル読み込み
   └─ docusaurus.config.jsからサイト設定を読み込み
2. Markdownファイル収集
   └─ docs/およびblog/ディレクトリからMDファイルを収集
3. Front Matter解析
   └─ 各ファイルのメタデータを抽出
4. Remarkプラグイン処理
   └─ GitHubメンション変換など前処理を実行
5. MDX変換
   └─ MarkdownをReactコンポーネントに変換
6. ページレンダリング
   └─ React ServerSideRenderingによりHTML生成
7. 検索インデックス生成
   └─ docusaurus-search-localによるインデックス作成
8. 画像最適化
   └─ IdealImageプラグインによる画像圧縮
9. 静的アセットコピー
   └─ static/ディレクトリ内容をbuild/にコピー
10. RSSフィード生成
    └─ ブログ記事からRSS XMLを生成
```

### フローチャート

```mermaid
flowchart TD
    A[yarn build 実行] --> B[設定ファイル読み込み]
    B --> C[コンテンツ収集]
    C --> D[Markdown解析]
    D --> E[Remarkプラグイン処理]
    E --> F[MDX変換]
    F --> G[React レンダリング]
    G --> H{ページタイプ}
    H -->|docs| I[ドキュメントページ生成]
    H -->|blog| J[ブログページ生成]
    H -->|pages| K[カスタムページ生成]
    I --> L[検索インデックス生成]
    J --> M[RSSフィード生成]
    K --> L
    L --> N[画像最適化]
    M --> N
    N --> O[静的アセットコピー]
    O --> P[build/ ディレクトリ出力]
    P --> Q[完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-71-01 | Front Matter必須 | タイトル未指定時は見出し1が必須 | 全ドキュメント |
| BR-71-02 | 画像命名規則 | ドキュメントに対応したプレフィックス付与 | 画像ファイル追加時 |
| BR-71-03 | 見出し階層 | H1は1つ、H2以降は階層に従う | ドキュメント作成時 |
| BR-71-04 | 言語 | 英語で記述 | 全ドキュメント |
| BR-71-05 | スクリーンショット形式 | PNG形式、ライトモード、1100x700px以内推奨 | 画像追加時 |
| BR-71-06 | GitHubメンション変換 | @username形式をGitHubリンクに自動変換 | ブログ・ドキュメント |

### 計算ロジック

画像最適化パラメータ:
- 品質: 70%
- 最大幅: 1030px
- 最小幅: 640px
- ステップ数: 2

Retinaディスプレイ対応:
- `@2x`サフィックスの画像は自動的に半分のサイズで表示

## データベース操作仕様

本機能はデータベースを使用しない静的サイト生成機能である。

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| BROKEN_LINKS | リンクエラー | 存在しないページへのリンク | リンク先修正またはページ作成 |
| BROKEN_MARKDOWN | Markdown構文エラー | 不正なMarkdown構文 | 構文修正 |
| SPELLING_ERROR | スペルエラー | 未登録の単語使用 | スペル修正またはキーワード登録 |
| IMAGE_NOT_FOUND | 画像エラー | 参照画像が存在しない | 画像パス修正または画像追加 |

### リトライ仕様

ビルドエラー時はエラーを解消後、再度ビルドコマンドを実行する。自動リトライ機能はない。

## トランザクション仕様

本機能は静的サイト生成であり、トランザクション制御は不要。

## パフォーマンス要件

- ビルド時間: 数分以内（フルビルド）
- 開発サーバー起動: 10秒以内
- HMR（Hot Module Replacement）: 即時反映

## セキュリティ考慮事項

- 静的サイトのため、サーバーサイド脆弱性リスクなし
- Netlifyのヘッダー設定（_headers）によるセキュリティヘッダー適用
- CORS設定は不要（静的コンテンツ配信）

## 備考

- Docusaurus v3.9.2を使用
- React 19系を採用
- Mermaid図表サポート
- ローカル検索機能（@easyops-cn/docusaurus-search-local）
- パンズーム機能（@r74tech/docusaurus-plugin-panzoom）

---

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

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

### 推奨読解順序

#### Step 1: プロジェクト構造とエントリーポイントを理解する

まず、Docusaurusプロジェクトの全体構造と設定を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | package.json | `packages/docs/package.json` | 依存関係とスクリプト定義を確認 |
| 1-2 | docusaurus.config.js | `packages/docs/docusaurus.config.js` | サイト全体設定（テーマ、プラグイン、ナビゲーション） |

**読解のコツ**: Docusaurusは設定駆動型のフレームワーク。`docusaurus.config.js`がすべての挙動を制御する。

**主要処理フロー**:
1. **1-7行目**: 依存パッケージ定義、Docusaurus Core v3.9.2使用
2. **6-14行目**: npm scriptsでビルド・開発サーバー起動
3. **12-17行目**: title/tagline/URLなど基本設定
4. **41-67行目**: preset-classic設定（docs、blog、テーマ）
5. **68-190行目**: themeConfig（ナビバー、フッター、色設定）
6. **191-213行目**: プラグイン設定（画像最適化、検索、パンズーム）

#### Step 2: サイドバー構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | docs-sidebar.js | `packages/docs/docs-sidebar.js` | ドキュメント階層構造とナビゲーション定義 |

**主要処理フロー**:
- **16-335行目**: サイドバー定義オブジェクト。カテゴリ、リンク、折りたたみ設定を含む
- **20-36行目**: "A Tour of Actual"カテゴリ定義例
- **227-244行目**: APIセクションの階層構造例

#### Step 3: カスタムコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.jsx | `packages/docs/src/pages/index.jsx` | ホームページ構造とカスタムコンポーネント使用法 |
| 3-2 | Button.jsx | `packages/docs/src/components/Button.jsx` | 再利用可能ボタンコンポーネント |
| 3-3 | Image.jsx | `packages/docs/src/components/Image.jsx` | 画像最適化コンポーネント |
| 3-4 | DownloadCard.tsx | `packages/docs/src/components/DownloadCard.tsx` | ダウンロードカードコンポーネント |

**読解のコツ**: Docusaurusは`@theme`や`@site`などのエイリアスを使用。`@theme/Layout`はDocusaurusのレイアウトコンポーネントを参照。

**主要処理フロー** (index.jsx):
- **9-276行目**: ホームページ全体構造
- **70-111行目**: MediumFeatureコンポーネントによる機能紹介
- **114-150行目**: BigFeatureコンポーネントによる主要機能紹介
- **279-291行目**: SmallFeatureコンポーネント定義
- **294-311行目**: MediumFeatureコンポーネント定義

#### Step 4: Remarkプラグインを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | mentions.js | `packages/docs/src/remark/mentions.js` | GitHubメンション自動変換プラグイン |

**主要処理フロー**:
- **3-42行目**: @username形式をGitHubプロフィールリンクに変換する処理
- **4行目**: 正規表現パターン `/@([\w-]+)/g`
- **18-28行目**: リンクノード生成処理

#### Step 5: テーマカスタマイズを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | custom.css | `packages/docs/src/css/custom.css` | グローバルスタイル定義 |
| 5-2 | MDXComponents.js | `packages/docs/src/theme/MDXComponents.js` | MDXコンポーネント拡張 |

**主要処理フロー** (custom.css):
- **7行目**: Google Fontsインポート（Libre Baskerville、Inter）
- **24-34行目**: ライトモードのカラー変数定義
- **37-46行目**: ダークモードのカラー変数定義

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

```
yarn build / yarn start
    │
    ├─ docusaurus.config.js (設定読み込み)
    │      ├─ presets/classic (docs, blog, theme)
    │      ├─ plugins/ideal-image (画像最適化)
    │      ├─ plugins/search-local (検索インデックス)
    │      └─ plugins/panzoom (図表ズーム)
    │
    ├─ docs-sidebar.js (サイドバー構造)
    │
    ├─ src/remark/mentions.js (Markdownプリプロセッサ)
    │
    ├─ docs/**/*.md (ドキュメントコンテンツ)
    │
    ├─ blog/**/*.md (ブログコンテンツ)
    │
    ├─ src/pages/*.jsx (カスタムページ)
    │      ├─ index.jsx (ホームページ)
    │      ├─ download.md (ダウンロード)
    │      └─ contact.md (コンタクト)
    │
    ├─ src/components/ (共通コンポーネント)
    │      ├─ Button.jsx
    │      ├─ Image.jsx
    │      ├─ DownloadCard.tsx
    │      └─ HomepageFeatures/index.jsx
    │
    ├─ src/theme/ (テーマオーバーライド)
    │      ├─ MDXComponents.js
    │      └─ Layout/index.jsx
    │
    └─ static/ (静的アセット)
           ├─ img/ (画像)
           ├─ _headers (Netlifyヘッダー)
           └─ _redirects (Netlifyリダイレクト)
```

### データフロー図

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

Markdownファイル ─────────┐
(docs/**/*.md)            │
                          │
ブログMarkdown ──────────┼────▶ Docusaurus ────────────────────────▶ build/
(blog/**/*.md)            │     │  ├─ Markdown解析                     ├─ index.html
                          │     │  ├─ MDX変換                          ├─ docs/**/*.html
JSXページ ───────────────┼────▶│  ├─ Reactレンダリング                 ├─ blog/**/*.html
(src/pages/*.jsx)         │     │  ├─ CSS/JS バンドル                  ├─ assets/
                          │     │  └─ 最適化                           ├─ img/
設定ファイル ─────────────┼────▶│                                       ├─ search-index.json
(docusaurus.config.js)    │     │                                       └─ blog/rss.xml
                          │     │
静的アセット ─────────────┘     └─ そのままコピー ──────────────────▶ static/**
(static/**)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| package.json | `packages/docs/package.json` | 設定 | 依存関係・スクリプト定義 |
| docusaurus.config.js | `packages/docs/docusaurus.config.js` | 設定 | サイト全体設定 |
| docusaurus.netlify-config.js | `packages/docs/docusaurus.netlify-config.js` | 設定 | Netlify用設定拡張 |
| docs-sidebar.js | `packages/docs/docs-sidebar.js` | 設定 | サイドバーナビゲーション定義 |
| babel.config.js | `packages/docs/babel.config.js` | 設定 | Babel設定 |
| index.jsx | `packages/docs/src/pages/index.jsx` | ソース | ホームページコンポーネント |
| download.md | `packages/docs/src/pages/download.md` | コンテンツ | ダウンロードページ |
| contact.md | `packages/docs/src/pages/contact.md` | コンテンツ | コンタクトページ |
| Button.jsx | `packages/docs/src/components/Button.jsx` | ソース | ボタンコンポーネント |
| Image.jsx | `packages/docs/src/components/Image.jsx` | ソース | 画像最適化コンポーネント |
| DownloadCard.tsx | `packages/docs/src/components/DownloadCard.tsx` | ソース | ダウンロードカード |
| HomepageFeatures/index.jsx | `packages/docs/src/components/HomepageFeatures/index.jsx` | ソース | ホーム機能紹介 |
| Key.jsx | `packages/docs/src/components/Key.jsx` | ソース | キーボードショートカット表示 |
| mentions.js | `packages/docs/src/remark/mentions.js` | ソース | GitHubメンション変換 |
| custom.css | `packages/docs/src/css/custom.css` | スタイル | グローバルCSS |
| MDXComponents.js | `packages/docs/src/theme/MDXComponents.js` | ソース | MDXコンポーネント拡張 |
| Layout/index.jsx | `packages/docs/src/theme/Layout/index.jsx` | ソース | レイアウトオーバーライド |
| index.md | `packages/docs/docs/index.md` | コンテンツ | ドキュメントトップ |
| writing-docs.md | `packages/docs/docs/contributing/writing-docs.md` | コンテンツ | ドキュメント執筆ガイド |
| README.md | `packages/docs/README.md` | ドキュメント | パッケージ説明 |
| _headers | `packages/docs/static/_headers` | 設定 | Netlifyヘッダー設定 |
| _redirects | `packages/docs/static/_redirects` | 設定 | Netlifyリダイレクト設定 |
