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

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

🧭 はじめに

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

目的は以下の3点に集約される：本手順では特に、章・記事（Page）には数値プレフィックスを付けないという方針を明確にする。 これはBookStackのソート仕様を正しく前提にした、長期運用向けの設計判断である。

  • 手作業を避け、短時間・低ミスでページ枠を作る
  • BookStackの内部構造を壊さず、安全に作成する
  • 再実行・再利用できるバッチ処理にする

🎯 この手順でできること

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

ノート作成の初動コストを極限まで下げられる。構造を壊さず、将来の挿入・削除に強いノート基盤を一気に用意できる。

🧱 前提条件

🔑 必須条件

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

  • 管理者権限ユーザー

  • 対象の

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

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

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

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

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

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

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

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

✅ 正しい役割分担

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

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

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

手順

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

  2. Users → 自分のユーザー

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

  4. 以下を控える：

    • Token ID
    • Token Secret

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

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

なぜAPIを使うのか

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

    • pages
    • revisions
    • permissions
    • activity_log

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

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

🛠️ 実装手順（bash + curl）

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

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

番号プレフィックスを付けることで、タイトルは並び順が将来も安定内容の意味のみする。を表し、順序は持たせない。

② API接続情報を設定

API_URL="https://your-bookstack.example.com/api/pages"
TOKEN_ID="xxxxx"
TOKEN_SECRET="yyyyy"
CHAPTER_ID=123
  • CHAPTER_ID は作成先ChapterのID
  • ChapterのURLを見ると数値で確認できるChapterのURLから数値で確認できる

③ バッチでページを一括作成

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

htmlフィールドは空にできない。
`

` のような最小ダミーを必ず入れる。

✅ 実行後の確認

  • Chapter配下に

    • タイトルのみのページが21個並んでいる
    Chapter配下に、タイトルのみのページが作成されている

  • 各ページは通常通り編集可能

    ページ順はUI上で自由に並び替え可能

  • URL・履歴・権限が正しく付与されている

    各ページは通常どおり編集・分割・移動できる

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

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

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

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

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

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

BookStackは「後から整理する」後から並び替える」ことを前提にした設計。
最初から完璧を目指さない。

上に戻る