第2章ファイルとディレクトリの規約

2.1 1 概念 = 1 ファイル

正本は 1 概念 = 1 Markdown ファイルで構成する。「概念」とは、業務索引・データ要件スキーマ・コード語彙・機能要件・法令・告示といった、参照の単位となるまとまりである。

1 ファイルは次の構造をとる（yaml／text のフェンスは本文中に置くコードブロックを表す）。

---
<YAML frontmatter>     # 索引層（第3章）
---
# 見出し
本文（趣旨・解説・図表）   # 知識層（第4章）

```yaml                # 正本層（第5章）。型付きデータ
...
```

```text                # 規範文（第4章）。byte 保持
...
```

frontmatter は必須。本文・payload・規範文は概念の性格に応じて持つ。

2.2 ディレクトリ＝アイデンティティ

ファイルのパスがその概念の所在を表す。URL もパスに一致させる（SSG はパスをそのまま URL にする）。標準仕様の正本系統は次のディレクトリ構造をとる。

businesses/<業務>/          # 業務単位（例 001-juki）
  index.md                  # 業務索引
  spec/                     # 機能要件（章ごとに分割）
    index.md
    01-....md
  data-list.md              # データ要件（基本データリスト）
  codes.md                  # コード一覧
  er.md                     # データモデル
  linkage-spec.md           # 連携要件
laws/                       # 法令・省令
guidelines/<ds-NNN>/        # ガイドライン（章ごとに分割）
character-standard/         # 文字要件

業務コードのような「粗くて安定した軸」を上位に、種別を下位に置く。これは URN の構成（第6章）と一致する。

2.3 章分割の規約

仕様書本文・ガイドライン・本書のような長文は、章ごとにファイルを分割し、ディレクトリにまとめる。

ディレクトリ直下に index.md（序文＋章目次）を置く。
章ファイルは NN-slug.md（2 桁連番＋英小文字スラッグ）で、連番が章順を表す。
各章ファイルの本文は H1（#）見出しで始める。章内の節は H2 以下を用いる。
見出しレベルは歯抜けにせず連続させる（H1 の次は H2、H2 の次は H3）。

SSG は index.md＋章ファイル群を検出し、章一覧と見出しアウトラインを持つサイドバーを自動生成する。ファイル名の連番が章の並び順、本文の H1 が章タイトル、H2 以下がアウトラインになる。

2.4 ファイル名に意味を埋めない

旧来の変換物は 001_住民基本台帳_基本データリスト【第2.4版】_20250228.md のように、ファイル名に業務名・種別・版・日付を詰め込んでいた。テキスト正本ではこれらをすべて frontmatter のキーへ昇格 させ、ファイル名は安定したスラッグ（data-list.md）に保つ（第3章）。版や日付が変わってもファイル名＝ URL を変えないためである。

2.5 添付資産（画像・SVG・CSV・フォント）

本文から参照する画像・図・データファイルは、概念ファイルと同じディレクトリかその assets/ 配下にパス保持で置き、本文からは相対パス（./assets/... または ../assets/...）で参照する。