Book Formatter

設定駆動型のブック生成システム - Book Publishing Template v3.0対応

概要

Book Formatterは、標準book.yamlを起点とするマルチチャネルadapterと、既存book-config.json / Jekyll書籍の互換保守機能を提供します。新規Web書籍は標準formatとweb-mdbookを使用し、従来のJekyll / GitHub Pages生成・同期経路はweb-jekyll-legacyとして維持します。

出力先の選択、実装済みadapter、legacy境界は出力target方針を参照してください。

特徴

⚡ 高速生成: 標準Web書籍の検証・出力と既存legacy書籍の保守を自動化
🔧 設定駆動: JSON/YAML設定ファイルでカスタマイズ
📝 マルチチャネル基盤: 標準Markdown / mdBookと既存Jekyll / GitHub Pages互換
🛡️ バリデーション: 設定ファイルの自動検証
🔄 自動更新: 既存書籍の構造を自動更新
🧪 テスト対応: 充実したテストスイート
🌐 日本語対応: 日本語技術書に最適化

インストール

# リポジトリをクローン
git clone https://github.com/itdojp/book-formatter.git
cd book-formatter

# 依存関係をインストール
npm install

# 実行権限を付与（Unix系）
chmod +x src/index.js

使用方法

新規標準Web書籍

新規Web書籍はexamples/standard-bookを基準にbook.yaml、標準Markdown、editionを定義し、web-mdbookへ出力します。

export BOOK_ROOT=./my-book
export BOOK_EDITION=free
export BOOK_OUTPUT_ROOT=dist
(
set -euo pipefail
npm run validate:standard-book -- "$BOOK_ROOT"
npm start build -- \
  --book "$BOOK_ROOT" \
  --target web-mdbook \
  --edition "$BOOK_EDITION" \
  --out-dir "$BOOK_OUTPUT_ROOT"
)

adapter project生成後は、同じ変数を維持してweb-mdbook adapter contractのself-contained blockを実行します。このblockはprojectを同じsource snapshotから再生成し、公式binaryの固定URL・SHA-256検証、fresh directoryへの展開、mdBook 0.5.4 gate、決定的なsource再照合、responsive検査、生成後artifact visibility検査を1つのfail-fast実行単位で完了します。既存projectやbinaryは再利用しません。

以下のinit、create-book、update-book、sync-all-books、rollout-uxは、既存book-config.json / Jekyll書籍との互換commandです。新規標準formatへ暗黙変換するcommandではありません。consumer writeを行う互換commandはlegacy consumer mutation contractのfresh dependency bootstrap、固定SHA、clean linked worktree、有限allowlist、単一target、rollbackを要求します。mutation commandは既存node_modules/.binを先行利用するnpm startではなく、監査済みNode.js executableからnode src/index.jsを直接実行します。npm start / npm run devのcompatibility entrypointはmutation commandを受け付けません。詳細はweb-jekyll-legacy互換契約を参照してください。

1. 既存legacy書籍用サンプル設定ファイルの確認

# 既存book-config.jsonの再構築に使うサンプル設定ファイルを生成
npm start init

# または特定のパスに生成
npm start init --output ./my-book-config.json

2. 既存legacy書籍用設定ファイルの編集

生成されたサンプル設定ファイルを編集して、書籍の情報を設定します：

{
  "title": "私の技術書",
  "description": "素晴らしい技術書の説明",
  "author": "著者名",
  "version": "1.0.0",
  "language": "ja",
  "license": "CC BY-NC-SA 4.0",
  "repository": {
    "url": "https://github.com/username/repository.git",
    "branch": "main"
  },
  "structure": {
    "chapters": [
      {
        "id": "introduction",
        "title": "はじめに",
        "description": "この書籍について"
      },
      {
        "id": "getting-started",
        "title": "はじめ方",
        "description": "基本的な使い方"
      }
    ],
    "appendices": [
      {
        "id": "references",
        "title": "参考文献"
      }
    ]
  }
}

3. 設定ファイルのバリデーション

# 設定ファイルの検証
npm start validate-config

# 詳細な検証結果を表示
npm start validate-config --verbose

# 特定のファイルを検証
npm start validate-config --config ./path/to/config.json

4. 既存Jekyll書籍の再構築・保守（legacy）

この手順は既存Jekyll / GitHub Pages形式を生成・保守する場合のlegacy手順です。新規標準Web書籍の推奨経路ではありません。

🎯 7つのフェーズ概要

Phase 1: 既存consumerの状態確認 (30分)
- 現行構成とdefault branch SHAの監査
- 既存book-config.jsonの検証または再構築
Phase 2: 既存リポジトリ状態の確認 (30分)
- 監査済みbase SHAから隔離worktreeを作成
- 現在のGitHub Pages方式を読み取り専用で確認
Phase 3: Jekyll template差分の確認 (60分)
- 必須fileの有無とconsumer固有変更を確認
- navigation templateの差分を監査
Phase 4: 既存章ファイルの確認 (章数 × 15分)
- 既存章fileの構造を保持
- front matterの差分を監査
Phase 5: リンク設定の統一 (30分)
- index.md のリンク形式統一
- 章間リンクの設定
Phase 6: 品質保証とテスト (30分)
- 設定ファイル検証
- リンクチェック
- Unicode品質チェック（不可視文字/互換漢字/異体字セレクタ等）
- ビルドテスト
Phase 7: 公開前の最終確認 (30分)
- 全ページの表示確認
- コンテンツ品質確認

📋 詳細な手順書

既存Jekyll書籍の再構築・保守手順は次を参照してください：

📚 Legacy Jekyll Setup Guide

新規Web書籍ではこのlegacy手順やcreate-bookを使用せず、前述のbook.yaml + web-mdbook手順を使用します。

5. 既存書籍の更新

# interfaceの確認だけを行う
node src/index.js update-book --help

update-bookはlegacy consumer mutation contractのfresh dependency bootstrap、有限plan、固定formatter/base SHA、clean linked worktree、完全一致allowlistを要求します。dry-runを含む各実行で既存node_modulesを再利用せず、npm ci --ignore-scripts完了後だけconsumer runtimeを起動します。dry-runは--target省略時にplanの全consumerを検査します。managed pathを確定した後、writeは--targetで1 consumerだけを変更します。本文の自動生成は行いません。

6. 複数書籍の一括同期

# 有限plan全件を検査する（書込みなし）
node src/index.js sync-all-books --plan .codex-local/tmp/sync-plan.json --dry-run

sync-all-booksはdirectory globを使用しません。planは最大6件ですが、writeには--targetが必須で1 consumerだけを処理します。失敗時は対象をrollbackしてnon-zeroで終了し、後続へ継続しません。次consumerまたは失敗後の再開は、consumer別review gate後の別実行で明示します。

7. UXロールアウト（既存書籍向け）

# profile差分の予定だけを確認
node src/index.js rollout-ux --registry ./book-registry.json \
  --plan .codex-local/tmp/profile-plan.json --apply-ux-profile --dry-run

# 共通コアのみを適用（layouts/includes/assets）
node src/index.js rollout-ux --plan .codex-local/tmp/core-plan.json \
  --apply-ux-core --dry-run

# writeはweb-jekyll-legacy contractの隔離consumer task branchで実行
# runtimeが選択destinationとbook-config.jsonを最初のwrite前に検査
node src/index.js rollout-ux --plan .codex-local/tmp/core-plan.json \
  --target sample-book --apply-ux-core

補足:

--apply-ux-profile は --registry が必須です
profile用planはregistryPathとregistrySha256も必須とし、読み込み時にpathと内容を照合します
このcommandの book-registry.json は profile / modules を持つ legacy UX registryです。portfolio-level registry version 1との関係は docs/book-registry.md を参照してください。
profile/coreの非dry-runは共通transactionを通り、fixed SHA、clean linked worktree、全destination preflight、完全一致allowlist、rollback、単一targetを強制します。
詳細はlegacy consumer mutation contractとweb-jekyll-legacy contractを参照してください。
Book Sync workflowのpreview / writeも同じruntime境界を通る。既定preview、最大3冊、明示allowlist、権限・Open PR preflight、consumer別PRというworkflow gateを省略しないでください。

品質チェック（ローカル）

# リンク（内部リンク/アンカー）を検証
npm run check-links -- <book-dir>

# Unicode品質（不可視文字/互換漢字/異体字セレクタ等）を検出
npm run check-unicode -- <book-dir> --output unicode-report.json

# レイアウトリスク（長すぎる行/ワイドな表/大きい画像）をスキャン
npm run check-layout-risk -- <book-dir> --output layout-risk-report.json

# Markdown構造（Front Matter/見出しレベル/コードフェンス言語）を検証
npm run check-markdown-structure -- <book-dir> --output markdown-structure-report.json

# portfolio-level book registryのschemaと参照整合性を検証
npm run validate:book-registry

# 標準書籍のedition visibilityと任意の生成artifactを検証
npm run check-visibility -- examples/standard-book --edition free \
  --output tmp-reports/visibility/free.json

# web-mdbook adapterのbuild planを検証し、manifestを表示（書き込みなし）
npm start build -- --book examples/standard-book \
  --target web-mdbook --edition free --dry-run

# mdBook projectをdist/web-mdbookへ生成してbuild/viewportを検証
export BOOK_ROOT=examples/standard-book
export BOOK_EDITION=free
export BOOK_OUTPUT_ROOT=dist
npm start build -- --book "$BOOK_ROOT" \
  --target web-mdbook --edition "$BOOK_EDITION" --out-dir "$BOOK_OUTPUT_ROOT"

# 文章校正（textlint + PRH辞書）
npm run check-textlint -- <book-dir> --output textlint-report.json

# 技術文書プリセットも併用（任意）
npm run check-textlint -- <book-dir> --with-preset --output textlint-report.json

project生成後のmdBook build / viewport / artifact visibility検査は、web-mdbook adapter contractのself-contained fail-fast blockだけを正本として実行します。このblockが同じBOOK_ROOT、BOOK_EDITION、BOOK_OUTPUT_ROOTからprojectを再生成・再照合するため、既存projectや別の書籍/editionをvisibility検査へ渡しません。

標準書籍metadataは標準書籍フォーマット、有償本文と内部本文の分離はEdition visibilityと有償本文の混入防止、新規出力とlegacy経路の選択は出力target方針を参照してください。出力先adapterの責務、有限target、manifest version 1はAdapter開発契約を参照してください。

メンテナンススクリプト（運用者向け）

ロールアウト/点検用途の補助スクリプトを scripts/ に配置しています。共通のエラーハンドリング（429/secondary rate limit 等のリトライ、ログ、HTTPコード取得、レポート退避）は scripts/lib.sh に集約しています。

実行時のレポート類は tmp-reports/<script>/<timestamp>/ に自動退避します（tmp-* は .gitignore 対象）。

主なスクリプト:

scripts/check_pages.sh: 公開GitHub Pagesのトップ/共通アセット/ナビ由来ページのHTTPステータスを点検
scripts/add_nav_check_workflow.sh: Nav + Pages Link Check ワークフローを各書籍へ追加（ローカルclone前提）
scripts/rollout_unification.sh: 有限planから1 consumerだけへshared componentsを適用するwrapper。branch/commit/push/PRは行わず、consumer別review gateを要求
scripts/rollout_codeowners.sh: .book-formatter/** のCODEOWNERSを各書籍へ追加（ローカルclone前提）
scripts/rollout_fix_config_yaml.sh: docs/_config.yml の url/baseurl/repository を監査/正規化（監査がデフォルト）
scripts/fix_review_issues.sh: PRレビュー本文/インラインコメントをJSONとして収集し退避（API 429耐性あり）
scripts/fix_root_links.sh: "/..." のroot絶対リンクを監査/（任意で）relative_url へ置換
scripts/cleanup_defaults_and_root_index.sh: テンプレ由来のプレースホルダや二重indexの検出（監査のみ）

リトライ関連の環境変数（例）:

GH_RETRY_MAX_ATTEMPTS, GH_RETRY_SLEEP_BASE_SEC, GH_RETRY_SLEEP_MAX_SEC
CURL_RETRY_MAX_ATTEMPTS

CLIコマンド

コマンド	説明	オプション
`init`	サンプル設定ファイルを作成	`--output`, `--force`
`create-book`	legacy `book-config.json`からJekyll構成を生成（既存書籍の再構築用途）	`--config`, `--output`, `--force`
`update-book`	監査済みplanから既存書籍のmanaged metadata/templateを1冊更新	`--plan`, `--target`, `--dry-run`
`validate-config`	設定ファイルをバリデーション	`--config`, `--verbose`
`sync-all-books`	有限planの検査。writeは明示した1冊のみ	`--plan`, `--target`, `--dry-run`
`rollout-ux`	有限planのUX profile/core検査・単一consumer適用	`--plan`, `--target`, `--registry`, `--apply-ux-core`, `--apply-ux-profile`, `--dry-run`
`build`	標準書籍をadapter向けに検証しmanifestを生成	`--book`, `--target`, `--edition`, `--out-dir`, `--dry-run`

設定ファイル仕様

必須フィールド

title: 書籍のタイトル（100文字以内）
description: 書籍の説明（500文字以内）
author: 著者名

オプションフィールド

version: バージョン（semantic versioning形式）
language: 言語コード（デフォルト: "ja"）
license: ライセンス（デフォルト: "CC BY-NC-SA 4.0"）
repository: リポジトリ情報
ux: UXプロファイル/モジュール設定
structure: 書籍構造（章、付録）

章の設定

{
  "structure": {
    "chapters": [
      {
        "id": "chapter-id",        // 英小文字、数字、ハイフンのみ
        "title": "章のタイトル",
        "description": "章の説明（オプション）",
        "objectives": ["目標1", "目標2"]  // オプション
      }
    ]
  }
}

UX設定

{
  "ux": {
    "profile": "A",
    "modules": {
      "quickStart": true,
      "readingGuide": true,
      "checklistPack": false,
      "troubleshootingFlow": false,
      "conceptMap": true,
      "figureIndex": false,
      "legalNotice": false,
      "glossary": true
    }
  }
}

改善提案

Book Formatterの改善提案についてはIMPROVEMENT_PROPOSALS.mdを参照してください。

legacy commandで生成されるファイル構造

次はcreate-book / update-book互換commandのJekyll構造であり、新規標準Web書籍の構造ではありません。

my-book/
├── src/                    # 書籍のソースファイル
│   ├── chapter-*/         # 各章のディレクトリ
│   │   └── index.md      # 章のメインファイル
│   └── appendices/       # 付録ディレクトリ
├── assets/               # 画像、CSS等のアセット
├── templates/           # テンプレートファイル
├── scripts/             # ビルドスクリプト
├── tests/              # テストファイル
├── index.md            # メインのインデックスファイル
├── book-config.json    # 書籍設定ファイル
├── _config.yml         # Jekyll設定ファイル
├── package.json        # Node.js設定ファイル
└── README.md           # 書籍のREADME

開発

テストの実行

# すべてのテストを実行
npm test

# 特定のテストファイルを実行
npm test tests/BookGenerator.test.js

# カバレッジレポートを生成
npm run test:coverage

コードフォーマット

# コードをフォーマット
npm run format

# リンティング
npm run lint

デバッグ

# 開発モードで実行（ファイル監視）
npm run dev

# legacy create-book互換commandのデバッグ情報を有効にして実行
DEBUG=book-formatter:* npm start create-book

対応形式

入力: 標準book.yamlとlegacy JSON / YAML設定ファイル
出力: 標準Markdown / mdBook project、legacy Markdown / Jekyll HTML
将来対応予定: PDF、EPUB

システム要件

Node.js 20.19.0以上、22.13.0以上、または24.0.0以上
npm 8.0.0以上

トラブルシューティング

詳細なトラブルシューティングガイドはTROUBLESHOOTING.mdを参照してください。

よくある問題

設定ファイルのバリデーションエラー
```
npm start validate-config --verbose
```
ファイル権限エラー
```
chmod +x src/index.js
```

依存関係の問題

rm -rf node_modules package-lock.json
npm install

ログの確認

# legacy create-book互換commandの詳細ログを有効にして実行
DEBUG=* npm start create-book

貢献

フォークしてください
フィーチャーブランチを作成してください (git checkout -b feature/amazing-feature)
変更をコミットしてください (git commit -m 'Add amazing feature')
ブランチにプッシュしてください (git push origin feature/amazing-feature)
プルリクエストを作成してください

ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。

作成者

ITDO Inc. (株式会社アイティードゥ)
Email: knowledge@itdo.jp
GitHub: @itdojp

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
adapters		adapters
config		config
docs		docs
examples/standard-book		examples/standard-book
resources/prh		resources/prh
scripts		scripts
shared		shared
src		src
templates		templates
tests		tests
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
README.md		README.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
book-registry.example.yaml		book-registry.example.yaml
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation