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

🧩 BookStackでタイトルのみのページを一括作成する（API利用）

🧭 はじめに

この手順書は、BookStack上に「タイトルのみの空ページ」をまとめて作成するための実務向けガイドである。 天文学史ノートのように、先に構造（ページ枠）を一気に用意し、内容は後から埋める運用を前提としている。

🎯 この手順でできること

  • 指定したChapter配下に 「意味だけを持つタイトル」のページを一括生成
  • ページ順はBookStackのUIで自由に並び替え可能
  • 本文は後から編集（最初は空に近い状態）
  • BookStackの履歴・権限・URL構造を正しく維持

構造を壊さず、将来の挿入・削除に強いノート基盤を一気に用意できる。

🧱 前提条件

🔑 必須条件

  • BookStackがAPI対応バージョン（v0.27以降）

  • 管理者権限ユーザー

  • 対象の

    • Bookshelf
    • Book
    • Chapter が事前に作成済み

ページは必ずChapter配下に作成する。
Book直下に作ると、後から構造整理が煩雑になる。

📐 タイトル設計の原則（重要）

🚫 数値プレフィックスを付けない

  • Chapter / Page は本の中で自由にソート可能

  • タイトルに番号を含めると：

    • 挿入・削除時に欠番や重複が発生
    • 分割時にタイトルが不自然になる

章・記事タイトルに番号を入れてはいけない。
それは将来の編集コストを確実に増やす。

✅ 正しい役割分担

  • 順序管理：BookStackのUI（ドラッグ＆ドロップ）
  • 意味表現：タイトル文字列そのもの

順序はUI、意味はタイトル。

🔐 APIトークンの準備（初回のみ）

手順

  1. BookStack管理画面にログイン

  2. Users → 自分のユーザー

  3. API Tokens セクションで新規トークン作成

  4. 以下を控える：

    • Token ID
    • Token Secret

Token Secretは二度と表示されない。
必ず安全な場所に保存する。

🧠 実装方針（なぜAPIを使うか）

BookStackは以下を内部で連動管理している：

  • pages
  • revisions
  • permissions
  • activity_log

DBを直接書き換えてはいけない。
履歴破損・権限不整合・アップデート不能の原因になる。

→ 公式APIを使うのが唯一の安全ルート。

🛠️ 実装手順（bash + curl）

① Chapter IDを確認する

  • BookStackにログインした状態で、F12で開発ツールを開く
  • Consoleタブを開き、プロンプトに下記のJavaScriptを貼り付ける
fetch('/api/chapters', {
  headers: {
    'Accept': 'application/json'
  }
}).then(r => r.json()).then(console.log)
    JSONが下記のように出力されるので当該ChapterのIDをメモしておく 
    [
    {
        "id": 1,
        "slug": "aws-lightsailbookstack",
        "name": "AWS LightsailにBookStackをセットアップする",
        "description": "",
        "priority": 2,
        "book_id": 2,
        "created_at": "2025-05-11T08:56:49.000000Z",
        "updated_at": "2025-05-11T08:56:49.000000Z",
        "owned_by": 6,
        "book_slug": "fc221",
        "created_by": 6,
        "updated_by": 6
    },
    :

  {
  "data": [
       {
       :
       },
       {
          "id": 35,
          "slug": "74071",
          "name": "時系列",
          "description": "",
          "priority": 3,
          "book_id": 109,
          "created_at": "2025-12-30T06:45:35.000000Z",
          "updated_at": "2025-12-30T06:45:35.000000Z",
          "owned_by": 6,
          "book_slug": "061",
          "created_by": 6,
          "updated_by": 6
      }
   ]
}

    ② 作成するページタイトル一覧を定義（番号なし）

    titles=(
"天文学とは何か"
"天文学史をどう見るか"
"先史・古代文明の天文学"
"メソポタミア・エジプト天文学"
"ギリシャ天文学"
"中国天文学"
"インド・イスラーム天文学"
"中世ヨーロッパの宇宙観"
"観測精度の限界と停滞"
"地動説の登場"
"観測革命"
"物理法則の導入"
"万有引力と宇宙"
"望遠鏡の進化"
"分光学と恒星の正体"
"恒星の進化と分類"
"銀河の発見"
"相対論と宇宙"
"ビッグバン宇宙論"
"現代の観測技術"
"系外惑星と生命探査"
)

    タイトルは内容の意味のみを表し、順序は持たせない。

    ③ API接続情報とバッチ処理をまとめて定義する

    この手順では、BookStack APIに接続し、ページを一括作成するための実行用スクリプトを1つ作成する。 API接続情報は環境ファイルではなく、このスクリプト内で完結させる。

    📁 作業用スクリプトを作成する

    まず、任意の作業ディレクトリでスクリプトファイルを作成する。

    touch create_pages.sh

    このファイルが「設定」と「処理」の両方を持つ。
    .env のような環境ファイルではない。

    ✍️ スクリプトを編集する

    vim create_pages.sh

    🔧 スクリプト全文を記述する

    以下をそのままファイルに貼り付け、 必要な値だけ自分の環境に合わせて修正する。

    #!/bin/bash

# ===== BookStack API 接続情報 =====
API_URL="https://your-bookstack.example.com/api/pages"
TOKEN_ID="xxxxx"
TOKEN_SECRET="yyyyy"
CHAPTER_ID=123

# ===== 作成するページタイトル一覧 =====
titles=(
"天文学とは何か"
"天文学史をどう見るか"
"先史・古代文明の天文学"
"メソポタミア・エジプト天文学"
"ギリシャ天文学"
"中国天文学"
"インド・イスラーム天文学"
"中世ヨーロッパの宇宙観"
"観測精度の限界と停滞"
"地動説の登場"
"観測革命"
"物理法則の導入"
"万有引力と宇宙"
"望遠鏡の進化"
"分光学と恒星の正体"
"恒星の進化と分類"
"銀河の発見"
"相対論と宇宙"
"ビッグバン宇宙論"
"現代の観測技術"
"系外惑星と生命探査"
)

# ===== ページ一括作成処理 =====
for title in "${titles[@]}"; do
  curl -s -X POST "$API_URL" \
    -H "Authorization: Token $TOKEN_ID:$TOKEN_SECRET" \
    -H "Content-Type: application/json" \
    -d "{
      \"name\": \"$title\",
      \"html\": \"<p></p>\",
      \"chapter_id\": $CHAPTER_ID
    }"
done

    📌 各設定項目の意味

    API_URL
    • BookStackのページ作成API
    • /api/pages は固定
    • ドメイン部分のみ自分の環境に合わせる

    末尾にスラッシュは付けない。

    TOKEN_ID / TOKEN_SECRET
    • BookStack管理画面で発行したAPIトークン
    • Authorizationヘッダで使用される

    このスクリプトをGit管理してはいけない。
    Token Secretが漏洩するとBookStack全体が操作可能になる。

    CHAPTER_ID
    • ページを作成する親Chapterの数値ID

    確認方法：

    1. 対象Chapterをブラウザで開く
    2. URLを確認する

    例：

    https://your-bookstack.example.com/books/astronomy/chapter/12

    CHAPTER_ID=12

    Chapter名では指定できない。

    ▶️ スクリプトを実行する

    実行権限を付与してから起動する。

    chmod +x create_pages.sh
./create_pages.sh

    実行後、Chapterを再読み込みするとタイトルのみのページが作成されている。

    ⚠️ 注意点（重要）

    html フィールドは空にできない。
    <p></p> のような最小ダミーを必ず指定する。

    ✅ 実行後の確認

    • Chapter配下に、タイトルのみのページが作成されている
    • ページ順はUI上で自由に並び替え可能
    • 各ページは通常どおり編集・分割・移動できる

    この時点で「書くための器」だけが完成している状態。

    🧠 運用上のベストプラクティス

    • 初期本文は以下でも可：

      <p><em>TODO</em></p>

    • 中身は1ページずつ順不同で書き始めてよい

    • 後からページを分割・統合してもURLは壊れない

    BookStackは「後から並び替える」ことを前提にした設計。

    上に戻る