# 機能設計書 75-Markdownサポート

## 概要

本ドキュメントは、Doom EmacsにおけるMarkdown文書の編集サポート機能について記述する。GitHub Flavored Markdown（GFM）を含む各種Markdown形式の編集、プレビュー、エクスポート機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Markdownは軽量マークアップ言語として広く普及しており、READMEファイル、ドキュメント、ブログ記事など様々な場面で使用されている。本モジュールはMarkdown文書の効率的な編集環境を提供し、プレビュー、複数のMarkdownプロセッサのサポート、GitHub風スタイリングを実現する。

**機能の利用シーン**：
- READMEファイルの編集
- 技術ドキュメントの作成
- ブログ記事の執筆
- Wikiページの編集
- プレビュー確認とHTMLエクスポート

**主要な処理内容**：
1. markdown-modeによる基本編集機能（シンタックスハイライト、インデント）
2. gfm-modeによるGitHub Flavored Markdownサポート
3. 複数のMarkdownプロセッサ対応（marked, pandoc, markdown, multimarkdown）
4. リアルタイムプレビュー（grip-mode）
5. 目次自動生成（markdown-toc）
6. コードブロック編集（edit-indirect）
7. Tree-sitterによる高度な構文解析（markdown-ts-mode）
8. Evil統合（evil-markdown）

**関連システム・外部連携**：
- marked: Node.jsベースのMarkdownプロセッサ
- pandoc: 汎用ドキュメント変換ツール
- multimarkdown: 拡張Markdownプロセッサ
- grip: GitHubスタイルプレビュー

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Markdownバッファ | 主画面 | Markdownファイルの編集 |
| - | *markdown-output*バッファ | 結果表示画面 | プレビュー表示 |
| - | ブラウザ | 結果表示画面 | HTMLプレビュー表示 |

## 機能種別

言語サポート / 文書作成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +grip | フラグ | No | gripプレビューを有効化 | doom!ブロックで指定 |
| +tree-sitter | フラグ | No | Tree-sitterサポートを有効化 | doom!ブロックで指定 |

### 入力データソース

- Markdownファイル（*.md, *.markdown）
- READMEファイル（README, README.md）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| HTML | ファイル/バッファ | markdown-export によるエクスポート |
| プレビュー | バッファ/ブラウザ | markdown-preview またはgrip-mode |
| 目次 | テキスト | markdown-toc-generate-toc |

### 出力先

- HTMLファイル: ソースファイルと同じディレクトリ
- プレビューバッファ: *markdown-output*
- ブラウザ: grip-mode使用時

## 処理フロー

### 処理シーケンス

```
1. Markdownファイルを開く
   └─ README ファイルは gfm-mode、その他は markdown-mode
2. モード初期化
   └─ シンタックスハイライト、キーバインド設定
3. プレビュー/エクスポート要求
   └─ +markdown-compile関数が適切なプロセッサを選択
4. コードブロック編集
   └─ edit-indirect でネイティブモードで編集
```

### フローチャート

```mermaid
flowchart TD
    A[Markdownファイルを開く] --> B{READMEファイル?}
    B -->|Yes| C[gfm-mode起動]
    B -->|No| D[markdown-mode起動]
    C --> E{+tree-sitter?}
    D --> E
    E -->|Yes| F[markdown-ts-mode]
    E -->|No| G[標準モード]
    F --> H[編集作業]
    G --> H
    H --> I{操作選択}
    I -->|プレビュー| J[+markdown-compile]
    I -->|エクスポート| K[markdown-export]
    I -->|コード編集| L[markdown-edit-code-block]
    J --> M{プロセッサ選択}
    M -->|marked| N[marked --gfm]
    M -->|pandoc| O[pandoc -f markdown]
    M -->|markdown| P[Markdown.pl]
    M -->|multimarkdown| Q[multimarkdown]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | READMEファイル判定 | /README または README.md は gfm-mode で開く | ファイルオープン時 |
| BR-02 | プロセッサ選択順序 | marked → pandoc → markdown → multimarkdown の順で試行 | プレビュー/エクスポート時 |
| BR-03 | GFMオプション | gfm-mode時は marked に --gfm --tables --breaks オプション付与 | marked使用時 |
| BR-04 | Rustハイライト | :lang rust モジュール有効時は rustic-mode でハイライト | コードブロック表示時 |
| BR-05 | フライスペル除外 | コードブロック、インラインコード、URL、HTML属性内は除外 | スペルチェック時 |

### 計算ロジック

特になし

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | user-error | Markdownプロセッサが見つからない | "No markdown program could be found" メッセージ表示 |

### リトライ仕様

複数プロセッサの順次試行（+markdown-compile-functions）

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

トランザクション管理なし

## パフォーマンス要件

- コードブロックのネイティブハイライトは delay-mode-hooks で最適化
- YAMLメタデータブロックの誤フォント化を防止するハック適用

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

- マウスクリックによるリンクフォローは無効化（誤クリック防止）

## 備考

- markdown-open-command はmacOSでは `open`、Linuxでは `xdg-open`
- GitHub CSSおよびhighlightjsをデフォルトスタイルとして使用

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

コンパイル関数リストを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/lang/markdown/config.el` | +markdown-compile-functions 変数 |

**読解のコツ**: この変数はプロセッサ選択のフックチェーンを定義。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/lang/markdown/config.el` | markdown-mode の use-package! 設定 |

**主要処理フロー**:
1. **18-19行目**: gfm-mode でREADMEファイルを開く
2. **21-52行目**: markdown-mode の初期設定
3. **29行目**: markdown-command に +markdown-compile を設定
4. **55-56行目**: flyspell predicate設定
5. **62-63行目**: smartparens バッククォート設定

#### Step 3: コンパイル関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload.el | `modules/lang/markdown/autoload.el` | +markdown-compile-* 関数群 |

**主要処理フロー**:
- **42-49行目**: `+markdown-compile` - フック実行
- **52-59行目**: `+markdown-compile-marked` - marked プロセッサ
- **62-70行目**: `+markdown-compile-pandoc` - pandoc プロセッサ
- **73-77行目**: `+markdown-compile-multimarkdown` - multimarkdown プロセッサ
- **80-85行目**: `+markdown-compile-markdown` - markdown/Markdown.pl プロセッサ

#### Step 4: Evil統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/lang/markdown/config.el` | evil-markdown 設定 |

**主要処理フロー**:
- **150-170行目**: evil-markdown-mode のキーバインド設定

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

```
markdown-mode / gfm-mode
    │
    ├─ markdown-preview / markdown-open
    │      └─ +markdown-compile
    │             ├─ +markdown-compile-marked
    │             ├─ +markdown-compile-pandoc
    │             ├─ +markdown-compile-markdown
    │             └─ +markdown-compile-multimarkdown
    │
    ├─ markdown-edit-code-block
    │      └─ edit-indirect
    │
    ├─ markdown-toc-generate-toc
    │
    └─ grip-mode (+grip フラグ)
           └─ GitHubスタイルプレビュー
```

### データフロー図

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

Markdownファイル ───────▶ markdown-mode ────────────▶ シンタックスハイライト
        │                      │
        │                      ▼
        └──────────────▶ +markdown-compile ─────────▶ HTMLバッファ/ファイル
                              │
                              ├─ marked
                              ├─ pandoc
                              ├─ markdown
                              └─ multimarkdown
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/lang/markdown/config.el` | ソース | モジュール設定、キーバインド |
| autoload.el | `modules/lang/markdown/autoload.el` | ソース | コンパイル関数、flyspell predicate |
| packages.el | `modules/lang/markdown/packages.el` | ソース | 依存パッケージ定義 |
