メインコンテンツへスキップ

YAML 定義書（BookStack 骨格生成：Book直下ページ → 章 → 章配下ページ）

1. 目的

この YAML は、指定した Book（book_id） に対して以下を上から順に生成するための入力定義である。

  1. Book 直下ページ（pages）
  2. 章（chapters）（存在しなければ作成）
  3. 章配下ページ（chapters[].pages）

既存の同名ページは SKIP（作らない）。既存の同名章は再利用する。

2. スキーマ（仕様）

2.1 トップレベル

キー 型 必須 説明
book_id int 必須 BookStack の book id（名前ではなく ID）
wip_markdown string 必須 新規作成ページに入れる本文（Markdown）
pages list 任意 Book 直下に作るページの定義（上から順に処理）
chapters list 任意 章と章配下ページの定義（上から順に処理）

2.2 pages（Book 直下ページ）

pages は ページ名のリスト（最小構成）とする。

  • 同一性：book_id に紐づく既存ページの name と 完全一致
  • 一致したら SKIP
  • 一致しなければ 新規作成（book直下に作成）
pages:
  - "ページタイトル1"
  - "ページタイトル2"

2.3 chapters（章 + 章配下ページ）

chapters は 章オブジェクトのリスト。

キー 型 必須 説明
name string 必須 章名（完全一致で既存章を探索）
pages list 任意 章配下に作るページ名リスト（上から順に処理）

  • 章の同一性：book_id 内の章一覧から name 完全一致

    • あればその章を使用
    • なければ新規作成

  • 章配下ページの同一性：章内ページ一覧から name 完全一致

    • 一致したら SKIP
    • なければ 新規作成
chapters:
  - name: "01_総論"
    pages:
      - "なぜこの本を作るのか"
      - "読み方"

3. バリデーション規約（入力エラー扱い）

3.1 必須チェック

  • book_id が存在し、整数であること
  • wip_markdown が存在し、空でないこと（空許容にするなら要件で明記）

3.2 型チェック

  • pages がある場合は list で、要素はすべて string

  • chapters がある場合は list

    • 各要素は object で name（string）を必須
    • pages がある場合は list で、要素はすべて string

3.3 重複の扱い（推奨ルール）

（要件として明示がないため、安全側の推奨ルール）

  • pages 内で同じタイトルが複数回出たら 入力エラー
  • 章名が chapters 内で重複したら 入力エラー
  • 同一章の pages 内で同名が重複したら 入力エラー
  • Book直下 pages と章配下 pages の同名は 許容（別スコープなので）

4. サンプル YAML（実用例）

book_id: 123
wip_markdown: |
  # WIP
  このページは骨格のみ作成されています。
  後で本文を書いてください。

# 1) Book 直下ページ（先に全部処理される）
pages:
  - "はじめに"
  - "用語集"
  - "全体構成"

# 2) 章 → 3) 章配下ページ（上から順に処理）
chapters:
  - name: "01_総論"
    pages:
      - "この本の目的"
      - "読み進め方"

  - name: "02_規格の全体像"
    pages:
      - "ISO 26262 / 21434 とA-SPICEの役割分担"
      - "A-SPICEを軸にした規格全体設計の考え方"

  - name: "99_参考"
    pages:
      - "参考文献"
      - "リンク集"

5. 最小 YAML（動作確認用）

5.1 Book直下のみ

book_id: 123
wip_markdown: "WIP"
pages:
  - "はじめに"
  - "用語集"

5.2 章配下のみ

version: 1
book_id: 123
wip_markdown: "WIP"
chapters:
  - name: "01_総論"
    pages:
      - "この本の目的"

6. 実装上の読み取り順（仕様として固定）

  1. YAMLロード・バリデーション

  2. book_id の Book直下ページ一覧を取得（SKIP判定用）

  3. pages を上から順に処理（存在すればSKIP）

  4. chapters を上から順に処理

    • 章の存在確認（なければ作成）
    • 章内ページ一覧を取得（SKIP判定用）
    • 章配下 pages を上から順に処理（存在すればSKIP）
上に戻る