# 03. 文書設定リファレンス

体裁は Markdown 先頭の YAML front matter（`ohyna:`）で定義します。

構文は YAML、キーの意味は本製品契約です。準拠の切り分けは [10-準拠仕様マップ.md](./10-準拠仕様マップ.md) §6 を参照してください。

---

## 1. Front matter

### 1.1 形式

文書の先頭（任意の HTML コメントの直後）に次の形で書きます。

```yaml
---
ohyna:
  title: 文書タイトル
  style: blue
  font: noto
  lang: ja
  cover: true
  subtitle: 副題
  label: DOC
  meta:
    - 発行元
    - 2026-07
---

# 本文見出し
```

規則:

| 規則 | 内容 |
|------|------|
| 名前空間 | 設定は **`ohyna:` 配下** |
| キー名 | **camelCase**（例: `fontSize`、`coverPattern`） |
| 受理キー | `ohyna:` 配下の公式キー（本書の表） |
| BOM | 先頭の UTF-8 BOM は無視 |
| コメント | front matter 直前の `<!-- ... -->` は除去してから解釈 |

`ohyna` 以外のルートキーは保持され、GUI の「適用」でもそのまま残ります。

### 1.2 キー一覧

| キー | 型 | 必須 | 未指定時の扱い | 意味 |
|------|-----|------|----------------|------|
| `title` | string | **必須**（解析・GUI） | 空は未設定。表示時は本文先頭 `#` をフォールバックしうる | 表紙タイトル・HTML `<title>` |
| `style` | string | **必須**（解析・GUI） | 解決処理では `"blue"` | 色テーマ名 |
| `font` | string | **必須**（`fontFamily` があれば代替可） | 解決処理では `"noto"` | 本文フォントプリセット |
| `lang` | string | **必須**（解析・GUI） | 解決処理では `"ja"` | HTML の `lang` 属性。例: `ja`、`en` |
| `cover` | bool | 任意 | 概ね表紙あり | 表紙の有無 |
| `subtitle` | string | 任意 | `""` | 表紙サブタイトル |
| `label` | string | 任意 | `""` | 表紙パートラベル |
| `meta` | string[] または改行区切り string | 任意 | `[]` | 表紙フッタ行 |
| `rounded` | bool | 任意 | `true` | 角丸。`false` なら `radius` は `none` 相当 |
| `radius` | `none` / `sm` / `md` / `lg` | 任意 | `md` | 角丸サイズ |
| `fontFamily` | string | 任意 | なし | カスタム CSS `font-family`（プリセットを上書き） |
| `fontMono` | string | 任意 | Cascadia / Consolas 系 | コード用フォント |
| `fontSize` | CSS 長さ | 任意 | `10.5pt` | 本文サイズ（`pt`/`px`/`em`/`rem`/`%`） |
| `lineHeight` | 数値文字列 | 任意 | `1.7` | 行間 |
| `coverPattern` | 表紙キー | 任意 | `noise` | 表紙背景パターン |
| `coverGradient` | bool | 任意 | `true` | 設定キーとして保持。表紙の見た目は `coverPattern` と色テーマで決まる |
| `headingBand` | bool | 任意 | `true` | h2 の帯背景 |
| `tableHeaderFill` | bool | 任意 | `true` | 表ヘッダの濃色塗り |
| `letterSpacing` | CSS | 任意 | `0` | 字間 |
| `author` / `version` / `date` | string | 任意 | `""` | 文書メタ。`meta` が空なら表紙フッタへ自動流し込み |
| `pageSize` | `a4`/`a5`/`b5`/`letter` | 任意 | `a4` | 用紙サイズ |
| `pageOrientation` | `portrait`/`landscape` | 任意 | `portrait` | 向き |
| `marginPreset` | `narrow`/`normal`/`wide`/`custom` | 任意 | `normal` | 余白プリセット |
| `marginTop` 等 | number（mm） | 任意 | プリセット値 | `custom` 時の上下左右 |
| `pageHeader` / `pageFooter` | 定型キー | 任意 | `none` | 本文ページのヘッダ／フッタ（表紙 `meta` とは別） |
| `pageHeaderText` / `pageFooterText` | string | 任意 | `""` | 定型が `custom` のとき |
| `toc` | bool | 任意 | `false` | 自動目次（`[TOC]` 挿入） |
| `tocDepth` | `2`/`3` | 任意 | `3` | 目次の見出し深さ |
| `codeLineNumbers` | bool | 任意 | `false` | コード行番号 |
| `codeWrap` | bool | 任意 | `false` | コード折り返し |
| `codeFontSize` | CSS 長さ | 任意 | （本文連動） | コード専用サイズ |
| `linkUnderline` | bool | 任意 | `false` | リンク下線 |
| `linkThemeColor` | bool | 任意 | `true` | リンク色をテーマに合わせる |
| `watermark` | `none`/`draft`/`confidential`/`custom` | 任意 | `none` | 透かし |
| `watermarkText` | string | 任意 | `""` | `custom` 時の文言 |
| `design` | object | 任意 | — | 上記レイアウト系をネストして書ける。フラットキーとマージ（ネスト側が優先） |

**必須の判定箇所**

- 画面の静的解析、およびプレビュー／PDF のゲート（必須キーが揃っているとき進む）

### 1.3 色テーマ（`style`）

画面のドキュメント設定で選べるテーマ:

| キー | 表示名 |
|------|--------|
| `blue` | 縹（はなだ／青） |
| `sky` | 空色（そらいろ／水色） |
| `indigo` | 藍（あい／紺） |
| `celadon` | 青磁（せいじ／青緑） |
| `forest` | 常磐（ときわ／緑） |
| `yellow` | 山吹（やまぶき／黄） |
| `default` | 琥珀（こはく／黄茶） |
| `gold` | 金色（こんじき／金） |
| `orange` | 柑子（こうじ／オレンジ） |
| `sakura` | 桜（さくら／ピンク） |
| `red` | 朱（あけ／赤） |
| `wine` | 蘇芳（すおう／赤紫） |
| `purple` | 藤（ふじ／紫） |
| `brown` | 焦茶（こげちゃ／茶） |
| `neutral` | 銀鼠（ぎんねず／灰色） |
| `dark` | 墨色（すみいろ／黒） |

図（Mermaid）の色と、印刷 CSS のアクセント色の両方に使います。

### 1.4 フォント

構成:

| 対象 | キー | 内容 |
|------|------|------|
| 本文 | `font` | プリセット（下表）。和文／欧文の優先ファミリーが異なる |
| 本文上書き | `fontFamily` | 任意の CSS `font-family` スタック（指定時は `font` より優先） |
| コード | `fontMono` | コード用スタック。空なら Cascadia Mono → Consolas → Courier New |
| サイズ／行間 | `fontSize` / `lineHeight` | 本文の基本サイズと行間 |

#### 本文プリセット（`font`）

| キー | 和文（優先） | 欧文（優先） |
|------|--------------|--------------|
| `noto` | Noto Sans JP | Segoe UI |
| `gothic` | 游ゴシック / ヒラギノ角ゴ / Noto Sans JP | Segoe UI |
| `mincho` | Noto Serif JP / 游明朝 / ヒラギノ明朝 | （和文スタックに追随） |
| `sans` | Noto Sans JP（フォールバック） | Segoe UI / system-ui |
| `serif` | Noto Serif JP（フォールバック） | Georgia / Times New Roman |
| `inter` | Noto Sans JP | Inter |
| `mono` | （欧文等幅を共用） | IBM Plex Mono |

#### コードフォント（`fontMono`）

GUI では次のプリセットから選び、YAML には CSS スタックを書き込みます（既定プリセット選択時はキー省略＝空）。

| GUI | 書き込まれるスタック（要約） |
|-----|------------------------------|
| Cascadia / Consolas（既定） | 空（実行時 Cascadia → Consolas → Courier New） |
| IBM Plex Mono | `"IBM Plex Mono", …` |
| Consolas | `Consolas, "Courier New", monospace` |
| カスタム | 利用者が入力した CSS |

Google Fonts から読み込むファミリーはプリセットごとに決まります。`fontFamily` に Noto が無い場合は日本語安全のため Noto Sans JP を追加することがあります。

### 1.5 角丸（`radius`）

| キー | CSS 変数の目安（sm / md / lg） |
|------|-------------------------------|
| `none` | 0 / 0 / 0 |
| `sm` | 3px / 6px / 8px |
| `md` | 6px / 10px / 14px |
| `lg` | 10px / 14px / 20px |

### 1.6 表紙デザイン（`coverPattern`）

表紙背景は色テーマ（`style`）と表紙デザイン（`coverPattern`）の組み合わせです。`solid` は単色です。

| キー | 表示名（GUI） |
|------|----------------|
| `noise` | 霞（かすみ／ぼかし） |
| `grainy` | 砂子（すなご／粒子） |
| `aurora` | 極光（きょっこう／オーロラ） |
| `mesh` | 彩雲（さいうん／メッシュ） |
| `solid` | 無地（むじ／単色） |
| `diagonal` | 斜影（しゃえい／斜め） |
| `horizontal` | 横霞（よこがすみ／横ぼかし） |
| `vertical` | 縦霞（たてがすみ／縦ぼかし） |
| `radial` | 円暈（えんうん／放射） |
| `split` | 二面（にめん／二分割） |
| `band` | 帯（おび／帯飾り） |
| `corner` | 隅取り（すみとり／コーナー） |
| `ribbon` | 側帯（そくたい／リボン） |
| `panel` | 脇板（わきいた／パネル） |
| `frame` | 額縁（がくぶち／フレーム） |
| `glow` | 中暈（ちゅううん／中心光） |
| `dusk` | 黄昏（たそがれ／夕暮れ） |
| `mist` | 薄霧（うすぎり／ミスト） |
| `horizon` | 地平（ちへい／水平線） |
| `stripe` | 縦縞（たてじま／ストライプ） |
| `dots` | 点描（てんびょう／ドット） |
| `grid` | 方眼（ほうがん／グリッド） |
| `chevron` | 矢筈（やはず／シェブロン） |
| `diamond` | 菱（ひし／ダイヤ） |
| `hex` | 亀甲（きっこう／六角） |
| `triangle` | 鱗（うろこ／三角） |
| `checker` | 市松（いちまつ／チェッカー） |
| `herringbone` | 杉綾（すぎあや／ヘリンボーン） |
| `isometric` | 升目（ますめ／立体格子） |
| `lattice` | 組子（くみこ／格子） |
| `mosaic` | 寄木（よせぎ／モザイク） |
| `blades` | 切子（きりこ／鋭角） |
| `sunburst` | 日輪（にちりん／放射） |
| `spiral` | 渦（うず／スパイラル） |
| `orbit` | 周回（しゅうかい／軌道） |
| `circles` | 同心円（どうしんえん／円環） |
| `wave` | 波（なみ／ウェーブ） |
| `waves` | 連波（れんぱ／多重波） |
| `ripples` | 細波（さざなみ／さざ波） |
| `scallop` | 波縁（なみぶち／スカラップ） |
| `mountains` | 連山（れんざん／山並み） |
| `arcs` | 円弧（えんこ／アーク） |
| `zigzag` | 稲妻（いなずま／ジグザグ） |

`font` / `radius` / `coverPattern` は上表のキーを使います。未知の値は解決時に静的解析 error になります。

### 1.7 設定値の優先順位（共通）

同名の設定が複数あるときの解決規則（画面利用では主に 2〜3）:

1. **提供者が別経路で明示した非空の上書き**（ある場合）  
2. **front matter**（`ohyna:`）  
3. **テーマ／製品既定値**（例: `cover` の既定 true）

| 入力の形 | 解釈 |
|----------|------|
| キーなし／`null`／省略 | **未指定（UNSET）** → 下位へフォールバック |
| 空文字列 `""` | **未指定と同じ**（下位へフォールバック） |
| 非空の値 | **VALUE** → 採用 |