# テンプレートエンジン機能（将来構想）仕様
**最終更新**: 2026年3月3日
このドキュメントは、テンプレートエンジン機能（将来構想）の詳細仕様です。概要は [planned-features.md](planned-features.md) を参照してください。
> 🚧 **将来構想**
> この機能は正式バージョンリリース後の仕様策定段階です。現時点ではアイデアレベルであり、実装時期や詳細は未定です。
## 概要（テンプレートエンジン）
フロントマターで定義した変数をMarkdown本文中で展開できるテンプレートエンジン機能を提供します。既存のプラグイン構文をマクロとして転用することで、統一的な記法を実現します。
## 設計方針
**責務の分離**:
- **UMDパーサー**: テンプレート構文を特殊なHTML要素として出力
- **バックエンド**: 実際の変数展開・マクロ実行を担当（Nuxt/Laravel/その他）
このアプローチにより、UMDパーサーは言語非依存のまま、各バックエンドが最適な方法でテンプレート処理を実装できます。
## フロントマター変数定義
```umd
---
title: "ページタイトル"
author: "著者名"
date: 2026-02-13
is_template: true # テンプレートエンジン機能を有効化
config:
theme: "dark"
version: "1.0.0"
items:
- "アイテム1"
- "アイテム2"
- "アイテム3"
---
# {{ title }}
著者: {{ author }}
日付: {{ date }}
```
**テンプレートモードの有効化**:
- `is_template: true` を設定することで、if文やfor文などの制御構造のサポートを有効化します。
- このフラグがない場合、基本的な変数展開のみが機能し、制御構造は無視されます。
## 変数展開構文
### 基本的な変数展開
**構文**:
```umd
{{ variable }}
```
**UMDパーサー出力**:
```html
<data class="umd-var" value="variable">{{ variable }}</data>
```
または、フロントマターで定義された全変数を一覧として出力する場合：
```html
<datalist id="umd-frontmatter-vars">
<option value="title">ページタイトル</option>
<option value="author">著者名</option>
<option value="date">2026-02-13</option>
</datalist>
```
**特徴**:
- 各変数展開箇所は `<data>` 要素で表現
- `value` 属性に変数名を格納
- 元の構文をテキストとして保持（バックエンドでの処理を想定）
- フロントマターのトップレベル変数を参照
- ドット記法でネストされた値にアクセス: `{{ config.theme }}`
### 配列・オブジェクトのアクセス
```umd
{{ items.0 }} <!-- 配列のインデックスアクセス -->
{{ config.theme }} <!-- オブジェクトのプロパティアクセス -->
```
## マクロ機能（プラグイン構文の転用）
既存のプラグイン構文をマクロとして再利用します。
### マクロ定義（フロントマター）
```yaml
---
macros:
note: |
@callout(info){{
📝 **注意**: {content}
}}
button: |
&link(btn btn-primary){{[{text}]({url})}}
---
```
### マクロ呼び出し
```umd
@macro(note, content="これは重要な情報です");
@macro(button, text="クリック", url="/page");
```
**バックエンドでの展開イメージ**:
```umd
@callout(info){{
📝 **注意**: これは重要な情報です
}}
&link(btn btn-primary){{[クリック](/page)}}
```
## 条件分岐（提案）
```umd
@if(theme == "dark"){{
ダークモード用コンテンツ
}}
@if(version >= "1.0.0"){{
新バージョンの機能説明
}}
```
**UMDパーサー出力**:
```html
<template class="umd-plugin umd-plugin-if" data-condition="theme == 'dark'">
ダークモード用コンテンツ
</template>
```
## 繰り返し処理（提案）
```umd
@for(item in items){{
- {{ item }}
}}
```
**期待される出力** (バックエンド処理後):
```markdown
- アイテム1
- アイテム2
- アイテム3
```
## セキュリティ考慮事項
**XSS対策**:
- 変数展開時は自動的にHTMLエスケープを適用
- 生のHTMLを挿入する場合は明示的なマーカーが必要（例: `{{{ raw_html }}}`）
- バックエンド側で適切なサニタイゼーションを実装
**インジェクション対策**:
- フロントマターのYAML/TOML解析は信頼できるライブラリを使用
- マクロ定義の再帰呼び出しを制限（無限ループ防止）
- 変数名の検証（予約語・特殊文字のチェック）
## 実装の段階的アプローチ
**Phase 1**: 基本変数展開
- フロントマター変数の定義
- `{{ variable }}` 構文のHTML要素化
- バックエンドでの単純な変数置換
**Phase 2**: マクロ機能
- `@macro()` 構文のサポート
- フロントマターでのマクロ定義
- プラグイン構文への展開
**Phase 3**: 制御構文
- `@if()`, `@for()` のサポート
- 条件評価エンジンの実装
- ネストされた制御構文
## Twigとの比較
| 変数展開 | `{{ var }}` | `{{ var }}` | 同じ構文 |
| フィルター | `{{ var\|upper }}` | 未定 | バックエンド依存 |
| 条件分岐 | `{% if %}` | `@if(){{}}` | UMDプラグイン形式 |
| ループ | `{% for %}` | `@for(){{}}` | UMDプラグイン形式 |
| マクロ | `{% macro %}` | フロントマター定義 | YAML/TOML形式 |
| 継承 | `{% extends %}` | 未対応 | バックエンド責務 |
## 利用シーン
1. **ドキュメント生成**: バージョン番号、日付、著者情報の一括管理
2. **多言語対応**: フロントマターで言語を指定し、コンテンツを切り替え
3. **条件付きコンテンツ**: ターゲット環境（開発/本番）に応じた表示
4. **再利用可能なスニペット**: 頻出するコンテンツをマクロ化
## 未解決の課題
- **パフォーマンス**: 大量の変数展開・マクロ処理の最適化
- **エラーハンドリング**: 未定義変数、構文エラーの報告方法
- **ツールサポート**: エディタでのシンタックスハイライト、補完機能
- **キャッシング戦略**: テンプレート展開結果のキャッシュ方法
- **型システム**: 変数の型チェック（文字列、数値、配列など）