# UMD ファイル形式仕様
**最終更新**: 2026年9月9日
このドキュメントは `.umd`・`.umdt`・`.umdx` の**ファイル形式**を定義します。
UMDパーサー（umd-core）の内部動作については [`architecture.md`](../architecture.md) を参照してください。
---
## 1. ファイル拡張子
| `.umd` | UMDドキュメント本文 |
| `.umdt` | UMDテンプレート（[`template-engine-spec.md`](template-engine-spec.md) 参照） |
| `.umdx` | バイナリアセットバンドル（画像・フォントなどを内包） |
---
## 2. `.umd` ファイル構造
`.umd` ファイルはフロントマターと本文の2ブロックで構成されます。
```umd
<フロントマター>
<本文（UMD記法）>
```
フロントマターは**必須**です。本文は0文字以上のUMDテキストです。
---
## 3. フロントマター
### 3.1 デリミタ
フロントマターは開始・終了デリミタで囲みます。以下の2形式を受け付けます。
**YAML形式**（`---`）
```yaml
---
title: "ドキュメントタイトル"
type: article
---
```
**TSON形式**（`***`、推奨）
```umd
***
title: "ドキュメントタイトル"
type: "article"
***
```
TSONはUMD推奨フォーマットですが、型定義が未確定の間はYAMLも同等に有効です。
開始デリミタ（`---` または `***`）がファイル先頭行になければフロントマターなしとみなし、パーサーはエラーを返します。
### 3.2 フィールド定義
フロントマターは [Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md) に準拠します。OKFで未定義のフィールドはUMD拡張として追加します。
#### OKF準拠フィールド
| `type` | string | 任意 | 文書の種別。`article`・`reference`・`tutorial` など。ホストアプリが自由に定義する |
| `title` | string | **強く推奨** | 人間が読むための表示名。省略時はホストアプリがファイル名などからフォールバックする |
| `description` | string | 任意 | 一文の概要。インデックス生成・検索スニペット・プレビューに使用 |
| `resource` | URI string | 任意 | 文書が表す資産の正規URI。絶対URLまたはバンドル相対パス（`.umdx` への参照にも使用可） |
| `tags` | string[] | 任意 | 横断的な分類に使う短いラベル。例: `[tech, rust, parser]` |
OKFのオプションファミリー（Provenance・Trust・Lifecycle・Computation）も使用できます。詳細はOKF仕様を参照してください。
#### UMD拡張フィールド
| `lang` | BCP 47 string | 任意 | 文書の言語。例: `ja`・`en`・`zh-TW`。省略時はホストアプリのデフォルト言語を適用する |
| `dir` | string | 任意 | テキスト方向。`ltr`（左→右）・`rtl`（右→左）・`auto` のいずれか。省略時は `lang` から推定するか `ltr` をデフォルトとする |
| `author` | string または object | 任意 | 著者情報。文字列または `{name, url, email}` オブジェクト |
#### 拡張フィールド
OKFの仕様に従い、上記以外のキーも自由に追加できます。パーサーおよびホストアプリは未知のフィールドを保持し、ラウンドトリップ時に破棄してはなりません。
### 3.3 `title` が省略された場合の挙動
umd-core パーサー自体は `title` を必須としません（プラグイン内コンテンツの再パースなど、タイトルが不要なユースケースがあるため）。
`.umd` ファイルとして扱う場合、ホストアプリは次のいずれかの方法でフォールバックを実装することを推奨します。
1. ファイル名（拡張子なし）を表示タイトルとして使用する
2. パースは成功させ、`title` 欠落を警告としてレポートする
ファイルを拒否するエラーとして扱うかどうかはホストアプリが決定します。
---
## 4. 本文
フロントマター終端デリミタの次の行から本文が始まります。本文はUMD記法（CommonMark + UMD拡張構文）で記述します。
`title` をフロントマターで定義しているため、本文中の見出し1（`#`）はセクション見出しとして自由に使用できます。一般的なMarkdownの「見出し1は文書に1つだけ」という慣習はUMDドキュメントには適用されません。
---
## 5. 記述例
### 最小構成
```umd
***
title: "はじめてのUMD"
***
本文をここに書きます。
```
### 推奨構成
```umd
***
title: "UMD パーサー設計概要"
type: "article"
description: "umd-coreの3層アーキテクチャと遅延レンダリングモデルを解説します。"
tags: ["umd", "parser", "architecture"]
lang: "ja"
author: {name: "Logue"}
***
## はじめに
...
```
### 多言語対応例
同一ファイル名を維持し、`lang` フィールドで言語を区別します。
```umd
# document.umd（日本語版）
***
title: "設計概要"
lang: "ja"
***
```
```umd
# document.umd（英語版、別ディレクトリ）
***
title: "Design Overview"
lang: "en"
***
```
ファイル名を `document.ja.umd` のように言語サフィックスで変えることも慣習として許容しますが、UMD仕様としての正式なフィールドは `lang` です。
---
## 5.5 ボトムマター（Bottom Matter）
ボトムマターは本文末尾に置くオプションのメタデータブロックです。デリミタ形式はフロントマターと同じです。
```umd
***
title: "UMD パーサー設計概要"
***
## はじめに
本文...
***
key: value
***
```
### 構文規則
- ボトムマターは**任意**です（フロントマターは必須）。
- ファイルの最終行がデリミタ（`---` または `***`）で終わる場合、その直前のデリミタとの間をボトムマターとして解釈します。
- フロントマターと同じキー・値形式で記述します。
- デリミタの種類はフロントマターと一致させることを推奨しますが、混在しても構いません。
### 用途
ボトムマターの具体的な用途は未確定です。現時点で想定している候補を示します。
- **テンプレートエンジンの親方向バインディング**: `.umdt` テンプレートで子ドキュメントから親テンプレートへデータを渡す仕組みとして使用する可能性があります（詳細は [`template-engine-spec.md`](template-engine-spec.md) 策定時に決定）。
- **後処理メタデータ**: レンダリング後にホストアプリが付加する情報（生成日時・キャッシュキーなど）の格納領域。
パーサーはボトムマターを検出した場合、フロントマターと同様にキー・値のマップとして返却します。解釈はホストアプリに委ねます。
---
## 6. `.umdt` テンプレートファイル
`.umdt` の詳細は [`template-engine-spec.md`](template-engine-spec.md) を参照してください。フロントマターの形式は `.umd` と同じです。
---
## 7. `.umdx` バイナリアセットバンドル
`.umdx` 仕様は別ドキュメントで定義します（未策定）。