# 機能設計書 57-Markdown

## 概要

本ドキュメントは、space-vimにおけるMarkdownサポート機能の設計を定義する。vim-markdown、vim-markdown-toc、previmの3つのプラグインを組み合わせた包括的なMarkdown編集・プレビュー環境を提供する。

### 本機能の処理概要

Markdown文書の作成と編集を支援するため、構文ハイライト、目次自動生成、ブラウザプレビュー、見出し操作などの包括的な機能を提供する。

**業務上の目的・背景**：MarkdownはREADME、技術文書、ブログ記事など幅広い場面で利用される軽量マークアップ言語である。効率的な文書作成のためには、構文ハイライトだけでなく、目次生成、リアルタイムプレビュー、見出しレベルの操作などの支援機能が重要である。

**機能の利用シーン**：README.md、技術ドキュメント、ブログ記事などのMarkdown文書を編集する際に自動的に有効化される。LocalLeaderキーを使用した見出し操作、目次生成、ブラウザプレビューなどの機能により、効率的な文書作成が可能になる。

**主要な処理内容**：
1. Markdown構文のシンタックスハイライト（vim-markdown）
2. LaTeX数式構文のサポート
3. 目次（TOC）の自動生成と更新（vim-markdown-toc）
4. ブラウザでのリアルタイムプレビュー（previm）
5. 見出しレベル操作のキーバインディング
6. テーブル整列機能（Tabularize連携）
7. 絵文字補完（emoji連携）

**関連システム・外部連携**：vim-markdown、vim-markdown-toc、previmプラグインとの連携。text-alignレイヤーと連携したテーブル整列。emojiレイヤーと連携した絵文字補完。

**権限による制御**：特になし。レイヤー有効化によりすべての機能が利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | Goyo（集中執筆モード） | 補助機能 | Markdown執筆時の集中モードとして利用 |
| - | ブラウザプレビュー | 主機能 | previmによるMarkdownプレビュー表示 |

## 機能種別

構文解析 / 構文ハイライト / 言語サポート / ドキュメント支援 / プレビュー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:tex_conceal | String | No | LaTeX concealの設定 | 空文字推奨 |
| g:vim_markdown_math | Number | No | LaTeX数式サポート | 0または1 |
| g:vim_markdown_frontmatter | Number | No | YAMLフロントマターサポート | 0または1 |
| g:vim_markdown_conceal | Number | No | conceal機能 | 0または1 |
| g:vmt_auto_update_on_save | Number | No | 保存時TOC自動更新 | 0または1 |
| g:previm_open_cmd | String | No | プレビューブラウザコマンド | OS依存 |

### 入力データソース

- Markdownソースファイル（.md, .markdown）のバッファ内容
- YAMLフロントマター

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 構文ハイライト | 視覚表示 | Markdown構文のカラー表示 |
| 目次 | テキスト | 自動生成されたTOC |
| プレビュー | HTML | ブラウザで表示されるHTML |

### 出力先

- Vimエディタ画面（バッファ表示）
- 外部ブラウザ（プレビュー）

## 処理フロー

### 処理シーケンス

```
1. レイヤー読み込み
   └─ +lang/markdownレイヤーが有効化される
2. プラグイン読み込み
   └─ vim-markdown、vim-markdown-toc、previmがvim-plugにより読み込まれる
3. 設定適用
   └─ config.vimとautocmd/markdown.vimの設定が適用される
4. ファイル検出
   └─ .mdファイルオープン時にfiletypeがmarkdownに設定される
5. 構文ハイライト適用
   └─ vim-markdownの構文定義に基づきハイライトが適用される
6. ftplugin適用
   └─ キーバインディングとリンター設定が適用される
```

### フローチャート

```mermaid
flowchart TD
    A[Vim起動] --> B{markdownレイヤー有効?}
    B -->|Yes| C[プラグイン群読み込み]
    B -->|No| Z[終了]
    C --> D[設定適用]
    D --> E{.mdファイルを開く?}
    E -->|Yes| F[filetype=markdown設定]
    E -->|No| G[待機]
    G --> E
    F --> H[構文ハイライト適用]
    H --> I[ftplugin/markdown.vim適用]
    I --> J[キーバインディング有効化]
    J --> K[編集可能状態]
    K --> L{プレビュー?}
    L -->|Yes| M[previmでブラウザ表示]
    L -->|No| K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-57-01 | レイヤー依存 | +lang/markdownレイヤーの有効化が必要 | .spacevimファイルでレイヤー指定時 |
| BR-57-02 | ファイルタイプ検出 | .md, .markdownファイルで自動有効化 | ファイルオープン時 |
| BR-57-03 | 折り返し表示 | Markdownファイルはwrap有効 | ftplugin適用時 |
| BR-57-04 | TOC自動更新 | ファイル保存時に目次を自動更新 | g:vmt_auto_update_on_save=1 |
| BR-57-05 | タイマー遅延読み込み | timer機能有効時は1.3秒後に遅延読み込み | g:spacevim.timer=1 |

### 計算ロジック

特になし

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

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

該当なし（データベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | プラグイン未インストール | vim-plugによるインストール未完了 | :PlugInstall実行 |
| - | ブラウザ未検出 | previmがブラウザを見つけられない | g:previm_open_cmd設定 |
| - | mdlエラー | mdlコマンドが未インストール | mdlのインストール |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 大規模Markdownファイルでも構文ハイライトが適切に適用されること
- プレビュー更新：500ms以下

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

- previmは一時HTMLファイルを生成してブラウザで表示
- 信頼できるコンテンツのみプレビューすること

## 備考

- GFM（GitHub Flavored Markdown）形式のTOCを生成
- Goyoレイヤーと組み合わせることで集中執筆モードが利用可能
- Tagbarでの見出しナビゲーションに対応

---

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

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

### 推奨読解順序

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

Markdownレイヤーは複数の設定ファイルとftpluginで構成される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.vim | `layers/+lang/markdown/config.vim` | LaTeX数式設定の確認 |
| 1-2 | markdown.vim | `core/autoload/spacevim/autocmd/markdown.vim` | プラグイン初期化関数 |

**読解のコツ**: `g:vim_markdown_*`変数はplasticboy/vim-markdown固有の設定。`g:vmt_*`変数はvim-markdown-toc固有の設定。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+lang/markdown/packages.vim` | MPマクロによる3つのプラグイン登録を確認 |

**主要処理フロー**:
1. **1-5行目**: vim-markdown登録（timer有効時は遅延読み込み）
2. **7行目**: vim-markdown-toc登録（コマンド実行時のみ読み込み）
3. **8行目**: previm登録（markdownファイルタイプ+PrevimOpenコマンドで読み込み）
4. **9行目**: autocmdでプラグイン読み込み後にInit関数を呼び出し

#### Step 3: 設定ファイルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+lang/markdown/config.vim` | vim-markdown基本設定 |
| 3-2 | markdown.vim | `core/autoload/spacevim/autocmd/markdown.vim` | プラグイン詳細設定 |

**主要処理フロー（config.vim）**:
- **3行目**: `let g:tex_conceal = ''` - LaTeX conceal無効化
- **4行目**: `let g:vim_markdown_math = 1` - LaTeX数式サポート有効化

**主要処理フロー（autocmd/markdown.vim）**:
- **1-7行目**: OS別のブラウザコマンド設定（Safari/Chrome/google-chrome）
- **9-12行目**: Init関数でprevim設定
- **14-18行目**: vim-markdown設定（数式、フロントマター、conceal）
- **20-26行目**: vim-markdown-toc設定（自動更新、フェンス設定）

#### Step 4: ftplugin設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | markdown.vim | `core/ftplugin/markdown.vim` | Markdownファイル固有設定 |

**主要処理フロー**:
- **6行目**: `setlocal wrap` - 折り返し表示有効化
- **8-12行目**: 見出しレベル操作キーバインディング（LocalLeader + 1-5）
- **15行目**: `:MarkdownPreview` - プレビューコマンド
- **17行目**: `:GenTocGFM` - GFM形式TOC生成
- **19行目**: `:Toc` - TOCサイドバー表示
- **22-25行目**: text-alignレイヤー有効時のテーブル整列
- **27行目**: ALEリンター設定（mdl）
- **29行目**: CursorHoldでTOC自動更新
- **31-38行目**: Tagbar用マークダウン見出し設定
- **40-42行目**: timer遅延読み込み
- **44-46行目**: emoji補完機能

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

```
.spacevim (ユーザー設定)
    │
    └─ Layer '+lang/markdown' 有効化
           │
           ├─ packages.vim
           │      ├─ MP 'plasticboy/vim-markdown' (構文ハイライト)
           │      ├─ MP 'mzlogin/vim-markdown-toc' (TOC生成)
           │      └─ MP 'previm/previm' (プレビュー)
           │
           ├─ config.vim
           │      ├─ g:tex_conceal = ''
           │      └─ g:vim_markdown_math = 1
           │
           ├─ core/autoload/spacevim/autocmd/markdown.vim
           │      ├─ spacevim#autocmd#markdown#Init()
           │      ├─ previm設定
           │      ├─ vim-markdown設定
           │      └─ vim-markdown-toc設定
           │
           └─ core/ftplugin/markdown.vim
                  ├─ setlocal wrap
                  ├─ 見出し操作キーバインディング
                  ├─ TOC生成/更新キーバインディング
                  ├─ Tabularize連携
                  ├─ ALE linter設定
                  └─ Tagbar設定
```

### データフロー図

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

.spacevim ───▶ レイヤーシステム ───▶ プラグイン登録
                     │
                     ▼
.mdファイル ───▶ vim-markdown ───▶ 構文ハイライト
                     │
                     ▼
              ftplugin/markdown.vim
                     │
                     ├───▶ キーバインディング設定
                     │
                     ├───▶ vim-markdown-toc ───▶ TOC生成/更新
                     │
                     └───▶ previm ───▶ ブラウザプレビュー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+lang/markdown/packages.vim` | 設定 | プラグイン登録 |
| config.vim | `layers/+lang/markdown/config.vim` | 設定 | vim-markdown基本設定 |
| markdown.vim | `core/autoload/spacevim/autocmd/markdown.vim` | autoload | プラグイン初期化 |
| markdown.vim | `core/ftplugin/markdown.vim` | ftplugin | キーバインディング・エディタ設定 |
| LAYERS.md | `layers/LAYERS.md` | ドキュメント | レイヤー一覧とプラグイン情報 |
