基礎編

この Part ではインストールからプロジェクトの設定、Markdown での執筆方法、そしてビルドして確認するまで、ligarb で本を作るための基本をひと通り学びます。

1. はじめに

1.1 ligarb とは

ligarb は、複数の Markdown ファイルから単一の HTML ファイルを生成する CLI ツールです。 ソフトウェアのドキュメントやチュートリアルなど、「本」の形式で情報を整理したいときに最適です。

1.2 特徴

1.2.1 生成物

• 単一 HTML 出力: すべての章を1つの index.html にまとめます
• 検索可能な目次: 左サイドバーに目次を表示し、キーワードで絞り込めます
• 章の切り替え表示: JavaScript で章ごとにコンテンツを切り替えます
• パーマリンク対応: URL の # で特定の章に直接リンクできます
• パート・付録: 章をパートでグループ化し、付録を追加できます
• 前後ナビゲーション: 章の末尾に前後の章へのリンクが表示されます
• ダークモード: サイドバーのトグルボタンで切り替え可能です
• カスタム CSS: 独自のスタイルを適用できます
• GitHub 編集リンク: 各章に「Edit on GitHub」リンクを表示できます
• レスポンシブデザイン: PC でもスマートフォンでも快適に読めます
• 印刷対応: 印刷時はすべての章を展開して出力します

1.2.2 執筆支援

• AI による自動執筆: 企画書（brief.yml）を書いて ligarb write を実行するだけで、本の生成からビルドまで自動化できます
• コメント・レビュー機能: ligarb serve で本文中のテキストを選択してコメントすると、Claude が改善提案やパッチを返します。承認するとソースファイルに自動反映されます
• 手動 AI 連携: ligarb help の出力を AI に渡すことで、仕様を正確に理解した上で章の追加や編集を指示できます

1.3 類似ツールとの比較

Markdown から本を生成するツールはいくつかあります。ここでは代表的なものと ligarb の違いを紹介します。

1.3.1 mdBook

Rust 製のドキュメント生成ツールで、Rust 公式ドキュメントにも使われています。章ごとに別ページを生成するマルチページ構成が基本です。ligarb は全章を単一の HTML にまとめるため、ファイル1つを渡すだけで本全体を共有できます。

1.3.2 Honkit（旧 GitBook）

Node.js 製で、GitBook のオープンソースフォークです。単一ページ出力にも対応していますが、Node.js のビルド環境が必要です。ligarb は Ruby と少数の gem だけで動作し、設定も book.yml ひとつで完結します。

1.3.3 Sphinx

Python 製のドキュメント生成ツールで、reStructuredText や Markdown を扱えます。非常に多機能ですが、設定や拡張の学習コストが高めです。ligarb は「Markdown で書いて1コマンドでビルド」というシンプルさを重視しています。

1.3.4 Pandoc

あらゆるフォーマット間の変換に対応する汎用ツールです。複数の Markdown から単一 HTML を生成することも可能ですが、目次のサイドバーや章の切り替え表示、検索機能などは自分で用意する必要があります。ligarb はこれらを最初から組み込んでいます。

1.3.5 VitePress

Vue ベースの静的サイトジェネレータで、ドキュメントサイトの構築に広く使われています。dev server による即時プレビュー、Vue コンポーネントの埋め込み、SEO に有利なマルチページ出力など、公開ドキュメントサイト向けの機能が充実しています。一方 ligarb は単一 HTML 出力に特化しており、ホスティング不要でファイルを渡すだけで読めます。SEO が必要な公開ドキュメントサイトには VitePress が、社内マニュアルや配布用の本には ligarb が適しています。

1.3.6 ligarb の立ち位置

ligarb は「手軽に本を作って、そのまま配れる」ことに焦点を当てたツールです。単一 HTML への出力、サイドバー目次や検索の組み込み、AI との連携といった機能を、最小限の設定で利用できます。出力形式やテーマを細かくカスタマイズしたい場合は Sphinx や mdBook が適していますが、手元の Markdown をさっと本の形にまとめたいときに ligarb は力を発揮します。

1.4 このマニュアルについて

このマニュアル自体が ligarb で作られています。 以降の章で、インストールから本のビルドまでを解説します。

2. インストールと準備

2.1 必要な環境

ligarb を使うには以下が必要です:

• Ruby 3.0 以上
• Bundler（gem install bundler）

2.2 インストール

ligarb のリポジトリをクローンし、依存ライブラリをインストールします:

git clone https://github.com/ko1/ligarb.git
cd ligarb
bundle install

2.3 ヘルプの確認

インストールできたら、まず ligarb help コマンドで使い方を確認してみましょう:

ligarb help

ligarb のすべてのコマンドと設定項目が表示されます。困ったときはまずこのコマンドを参照してください。

2.4 プロジェクトの作成

本のプロジェクトを作成します。以下のディレクトリ構造を用意してください:

my-book/
├── book.yml
├── chapters/
│   ├── 01-first-chapter.md
│   └── 02-second-chapter.md
└── images/          # 画像がある場合
    └── screenshot.png

book.yml が設定ファイル、chapters/ 以下に各章の Markdown ファイルを配置します。

3. book.yml の書き方

3.1 基本構造

book.yml は YAML 形式の設定ファイルです。以下が基本的な構造です:

title: "本のタイトル"
author: "著者名"
language: "ja"
output_dir: "build"
chapters:
  - 01-introduction.md
  - 02-details.md

3.2 フィールド一覧

3.3 chapters の指定

chapters には章のファイルパスをそのまま並べることも、パートや付録で構造化することもできます。

3.3.1 表紙（カバーページ）

本の冒頭に表紙ページを追加できます。表紙は目次には表示されず、本を開いたときに最初に表示されるページになります:

chapters:
  - cover: cover.md
  - 01-introduction.md

3.3.2 シンプルな構成

章をフラットに並べるだけの最もシンプルな形式です:

chapters:
  - 01-introduction.md
  - 02-getting-started.md
  - 03-advanced.md

3.3.3 パート（部）で分ける

章が多い本では、パートでグループ化できます:

chapters:
  - part: part1.md
    chapters:
      - 01-introduction.md
      - 02-getting-started.md
  - part: part2.md
    chapters:
      - 03-advanced.md
      - 04-tips.md

part には Markdown ファイルを指定します。 そのファイルの h1 がパートのタイトルになり、本文が扉ページとして表示されます。

3.3.4 付録を追加する

巻末に付録を追加できます。付録の章にはアルファベット（A, B, C, …）で番号が付きます:

chapters:
  - part: part1.md
    chapters:
      - 01-introduction.md
  - appendix:
    - a1-references.md
    - a2-glossary.md

3.3.5 ファイル名の規約

ファイル名に決まりはありませんが、番号-スラッグ.md の形式にすると管理しやすくなります。 ファイル名の 番号-スラッグ 部分がそのまま章の識別子（slug）として URL の # に使われます。

3.4 カスタム CSS

style フィールドで CSS ファイルを指定すると、デフォルトスタイルの後に読み込まれます:

style: "custom.css"

CSS カスタムプロパティを上書きすることで、色やフォントなどを変更できます:

:root {
  --color-accent: #e63946;
  --sidebar-width: 320px;
}

3.5 GitHub 編集リンク

repository フィールドを指定すると、各章の末尾に「View on GitHub」リンクが表示されます（GitHub 編集リンク）:

repository: "https://github.com/user/my-book"

3.6 AI 生成マーク

ai_generated を true にすると、以下の効果があります:

• サイドバーに「AI Generated」バッジを表示
• 各章の末尾に免責事項のフッターを自動追加
• noindex / noai メタタグを追加（検索エンジンのインデックスと AI 学習を抑制）

ai_generated: true

3.7 フッター

footer フィールドで各章の末尾に表示するテキストを指定できます。ai_generated: true のデフォルト免責文を上書きすることもできます:

footer: "© 2025 著者名. All rights reserved."

3.8 参考文献

bibliography フィールドで参考文献データファイルを指定します。YAML（.yml）と BibTeX（.bib）の両形式に対応しています:

bibliography: references.bib

詳しい使い方は Markdown の書き方 を参照してください。

3.9 参照ファイル（sources）

sources フィールドは、AI 執筆（ligarb write）時に AI が参照するファイルを指定します。指定されたファイルの内容が AI へのコンテキストとして渡されます:

sources:
  - notes.md
  - path: data/research.pdf
    label: "調査レポート"

文字列で指定するとファイル名がそのままラベルになります。path と label を個別に指定することもできます。

3.10 多言語対応（translations / inherit）

translations フィールドで同じ本の複数言語版を管理できます。inherit フィールドで親設定の共通項目を継承できます。

# book.yml（ハブ）
repository: "https://github.com/user/repo"
translations:
  ja: book.ja.yml
  en: book.en.yml

# book.ja.yml（子）
inherit: book.yml
title: "マニュアル"
language: "ja"
chapters:
  - intro.md

詳しくは 6. 多言語対応（Translations） を参照してください。

4. Markdown の書き方と画像の配置

4.1 対応する Markdown 記法

ligarb は GitHub Flavored Markdown (GFM^{[GitHub, 2017]}) に対応しています。Markdown は John Gruber が 2004 年に発表^{[John, 2004]}した軽量マークアップ言語で、以下の記法が使えます。

4.1.1 見出し

見出しは # で記述します。h1〜h3 が目次に表示されます:

# 章タイトル（h1）
## セクション（h2）
### サブセクション（h3）

各章の最初の h1 がその章のタイトルとして目次に表示されます。

4.1.2 コードブロック

バッククォート3つで囲むと、コードブロックになります。 言語名を指定すると、自動的にシンタックスハイライトが適用されます:

def greet(name)
  puts "Hello, #{name}!"
end

def fibonacci(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a

const fetchData = async (url) => {
  const response = await fetch(url);
  return response.json();
};

シンタックスハイライトには highlight.js^{[Ivan, 2011]} が使われます。 言語指定のあるコードブロックが Markdown 内にある場合のみ、 ビルド時に自動でダウンロードされます。

4.1.3 ダイアグラム（mermaid）

` ```mermaid` で Mermaid のダイアグラムを描けます。 フローチャート、シーケンス図、クラス図など多くの図に対応しています。

フローチャート:

graph TD
    A[ユーザー] -->|リクエスト| B[Webサーバー]
    B --> C{認証済み?}
    C -->|Yes| D[コンテンツ配信]
    C -->|No| E[ログインページ]
    E -->|認証| C

シーケンス図:

sequenceDiagram
    participant U as ユーザー
    participant S as サーバー
    participant DB as データベース
    U->>S: リクエスト送信
    S->>DB: クエリ実行
    DB-->>S: 結果返却
    S-->>U: レスポンス

棒グラフ（xychart）:

xychart
    title "月別売上"
    x-axis ["1月", "2月", "3月", "4月", "5月", "6月"]
    y-axis "売上 (万円)" 0 --> 500
    bar [120, 230, 180, 350, 410, 300]
    line [120, 230, 180, 350, 410, 300]

折れ線グラフ（xychart、line のみ）:

xychart
    title "気温の推移"
    x-axis ["1月", "2月", "3月", "4月", "5月", "6月"]
    y-axis "気温 (℃)" -5 --> 30
    line [2, 4, 10, 16, 22, 26]

円グラフ:

pie title ブラウザシェア
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 4
    "Edge" : 4
    "その他" : 8

ガントチャート:

gantt
    title プロジェクト計画
    dateFormat YYYY-MM-DD
    section 設計
        要件定義      :a1, 2025-01-01, 14d
        基本設計      :a2, after a1, 10d
    section 開発
        実装          :b1, after a2, 21d
        テスト        :b2, after b1, 14d

マインドマップ:

mindmap
    root((ligarb))
        Markdown
            GFM
            コードブロック
            数式
        ビルド
            HTML生成
            アセット管理
        機能
            目次
            索引
            参考文献

Mermaid の詳しい記法は 公式ドキュメント を参照してください。

4.1.4 数式（KaTeX）

` ```math` で KaTeX^{[Khan, 2014]} による数式レンダリングが使えます。 LaTeX^{[Leslie, 1994]} 記法で数式を記述します。

二次方程式の解の公式:

ガウス積分:

行列:

4.1.5 関数グラフ（functionplot）

` ```functionplot` で関数のグラフを描画できます。

1行に1つの関数を書きます。y = <式> の形式が基本です:

極座標やパラメトリック曲線にも対応しています:

オプションは key: value の形式で指定します:

• range / xrange — X軸の範囲（例: [-2pi, 2pi]）
• yrange — Y軸の範囲
• width / height — サイズ（ピクセル、デフォルト: 600×400）
• title — グラフのタイトル
• grid: true — グリッド線の表示

これらの外部ライブラリは、該当するコードブロックが Markdown 内に存在する場合のみ ビルド時に自動的にダウンロードされ、build/js/ と build/css/ に配置されます。 既にダウンロード済みであればスキップされます。

4.1.6 インライン数式

文中に数式を埋め込むには $...$ で囲みます。例えば、有名な式 はこのように書けます:

有名な式 $E = mc^2$ はこのように書けます。

二次方程式の解 のような複雑な式もインラインで書けます。

4.1.7 テーブル

GFM のテーブル記法が使えます:

4.1.8 リスト

通常のリストとタスクリストに対応しています:

• 項目 1
• 項目 2
  • ネストも可能

1. 番号付きリスト
2. 二番目

4.1.9 引用

> これは引用です。
> 複数行に渡ることもできます。

4.1.10 Admonition（注意書きボックス）

GFM の blockquote alert 記法で、スタイル付きの注意書きボックスを作成できます:

記法は以下の通りです:

> [!NOTE]
> ここに補足情報を書きます。

> [!TIP]
> ここにアドバイスを書きます。

> [!WARNING]
> ここに注意事項を書きます。

> [!CAUTION]
> ここに危険な操作についての警告を書きます。

> [!IMPORTANT]
> ここに重要な情報を書きます。

対応するタイプは NOTE、TIP、WARNING、CAUTION、IMPORTANT の 5 種類です。

4.1.11 脚注

テキスト中に脚注を挿入できます¹。複数の脚注も使えます²。

テキスト中に脚注を挿入できます[^1]。

[^1]: これが脚注の内容です。

脚注の ID は章ごとにスコープされるため、異なる章で同じ番号を使っても衝突しません。

4.2 画像の配置

4.2.1 ディレクトリ

画像ファイルは images/ ディレクトリに配置します:

my-book/
├── book.yml
├── chapters/
│   └── 01-introduction.md
└── images/
    ├── screenshot.png
    └── diagram.svg

4.2.2 Markdown での参照

Markdown 内では相対パスで画像を参照します:

![スクリーンショット](images/screenshot.png)

ligarb はビルド時に画像パスを images/ファイル名 に書き換え、 images/ ディレクトリの中身を出力先にコピーします。

4.2.3 対応フォーマット

PNG, JPEG, SVG, GIF などの一般的な画像フォーマットが使えます。 画像はそのままコピーされるため、変換や最適化は行いません。

4.3 索引（Index）

本の末尾に索引を自動生成できます。Markdown のリンク記法を使って索引語をマークします。

4.3.1 基本的な使い方

リンク先に #index を指定すると、リンクテキストがそのまま索引語になります:

[Ruby](#index) は動的型付け言語です。

表示テキストと索引語を別にしたい場合は #index:索引語 とします:

[動的型付け言語](#index:動的型付け)

4.3.2 複数の索引語

カンマ区切りで一箇所に複数の索引語を登録できます:

[Ruby](#index:Ruby,プログラミング言語/Ruby)

4.3.3 階層化

/ で区切ると、索引が階層構造になります。例えば プログラミング言語/Ruby と書くと:

プログラミング言語
  Ruby ......... 4章

のように親子でグルーピングされます。

4.3.4 実際の例

以下はこのマニュアル内での索引マーカーの例です:

Markdown は軽量マークアップ言語です。 highlight.js によるシンタックスハイライト、 Mermaid によるダイアグラム、 KaTeX による数式レンダリングに対応しています。

索引マーカーは通常のテキストとして表示され、リンクのスタイルにはなりません。 本の末尾に「索引」セクションが自動的に追加されます。

4.4 参考文献（Bibliography）

本の中で参考文献を引用し、巻末に参考文献リストを自動生成できます。

4.4.1 設定

book.yml に参考文献データファイルを指定します。拡張子で形式が自動判定されます:

bibliography: references.yml   # YAML 形式
bibliography: references.bib   # BibTeX 形式

YAML 形式

キーと文献情報のマッピングです:

matz1995:
  author: "Yukihiro Matsumoto"
  title: "The Ruby Programming Language"
  year: 1995
  url: "https://www.ruby-lang.org"
  publisher: "O'Reilly"

BibTeX 形式（.bib）

標準的な BibTeX 記法で記述できます:

@book{matz1995,
  author = {Yukihiro Matsumoto},
  title = {The Ruby Programming Language},
  year = {1995},
  publisher = {O'Reilly},
  url = {https://www.ruby-lang.org}
}

@article{knuth1984,
  author = {Donald Knuth},
  title = {Literate Programming},
  year = {1984},
  journal = {The Computer Journal},
  volume = {27},
  number = {2},
  pages = {97-111}
}

BibTeX の注意事項:

• % で始まる行はコメントとして無視されます
• フィールド値は {...} または "..." で囲みます
• {The {Ruby} Language} のようなネスト 1 段階の波括弧に対応しています
• エントリタイプ（@book、@article 等）に応じて表示フォーマットが変わります

4.4.2 対応フィールド

以下のフィールドが YAML・BibTeX 共通で使えます:

4.4.3 エントリタイプ別の表示

BibTeX のエントリタイプに応じて参考文献リストのフォーマットが変わります:

• book: Author. Title. Edition. Publisher. Year.
• article: Author. “Title”. Journal, Volume(Number), pp. Pages. Year.
• inproceedings: Author. “Title”. In Booktitle, pp. Pages. Year.
• その他/YAML: Author. Title. Publisher. Journal. Volume. Pages. Year.

4.4.4 引用の書き方

リンク先に #cite:キー を指定します:

[Ruby](#cite:matz1995) は素晴らしい言語です。

これは「Ruby^{[Yukihiro, 1995]} は素晴らしい言語です。」のように表示されます。上付きの [著者姓, 年] は参考文献セクションへのリンクになっており、hover すると文献の完全な情報が表示されます。

4.4.5 実際の例

このマニュアル自体が参考文献機能を使っています。manual/references.bib に BibTeX 形式で文献を定義し、本文中で引用しています。

Markdown^{[John, 2004]} は 2004 年に発表された軽量マークアップ言語です。その後 GitHub が GFM として拡張^{[GitHub, 2017]}し、テーブルやタスクリストなどの機能が追加されました。数式のレンダリングには KaTeX^{[Khan, 2014]} を、シンタックスハイライトには highlight.js^{[Ivan, 2011]} を使用しています。数式記法は Lamport の LaTeX^{[Leslie, 1994]} に基づいており、コードブロックによる文書と実行コードの融合は Knuth の Literate Programming^{[Donald, 1984]} の影響を受けています。ハイパーリンクによる相互参照は Berners-Lee らの WWW^{[Tim, 1992]} の基本概念です。

上の例のソースは以下のようになっています:

[Markdown](#cite:gruber2004) は 2004 年に発表された...
[Knuth の Literate Programming](#cite:knuth1984) の影響を...
[Berners-Lee らの WWW](#cite:berners-lee1992) の基本概念です。

4.4.6 動作の詳細

• 参考文献セクションは索引の前に自動的に追加されます
• 参考文献は著者名・年でソートされます
• url がある場合、タイトルがリンクになります
• doi がある場合、末尾に DOI リンクが追加されます
• 存在しないキーを #cite: で参照すると警告が出力され、[key?] と赤色で表示されます（ビルドは中断しません）
• bibliography を設定していない場合、参考文献セクションは生成されません

4.5 相互参照（Cross-References）

他の章や見出しへのリンクを、標準の Markdown リンク記法で作成できます。 ビルド時に .md ファイルへの相対リンクが単一 HTML 内のアンカーに変換されます。

4.5.1 基本的な使い方

相互参照は通常の Markdown リンクとして記述します。リンク先に .md ファイルを指定すると、ビルド時に自動的に解決されます:

[設定の詳細](03-book-yml.md)

特定の見出しへリンクするには # でフラグメントを指定します:

[chapters フィールド](03-book-yml.md#chapters フィールド)

4.5.2 リンクテキストの自動挿入

リンクテキストを空にすると、リンク先の章タイトルや見出しテキスト（番号付き）が自動的に挿入されます:

詳しくは [](03-book-yml.md) を参照してください。
設定項目は [](03-book-yml.md#chapters フィールド) で説明しています。

上の例では、リンクテキストがそれぞれ「3. book.yml の設定」「3.1 chapters フィールド」のように章番号・セクション番号付きで表示されます。

4.5.3 パスの解決

.md のパスは、現在の Markdown ファイルのディレクトリからの相対パスとして解決されます。同じディレクトリにある章ファイルへはファイル名だけで参照できます。

4.5.4 エラー検出

参照先の章ファイルや見出しが存在しない場合、ビルドはエラーで停止します:

Error: cross-reference target not found: missing.md (from 01-introduction.md)
Error: cross-reference heading not found: 03-book-yml.md#typo (from 04-markdown.md)

5. ビルドと確認

5.1 ビルドコマンド

本のプロジェクトディレクトリで以下を実行します（ligarb build）:

ligarb build

book.yml が別の場所にある場合は、パスを指定できます:

ligarb build path/to/book.yml

5.2 出力結果

ビルドが成功すると、output_dir に指定したディレクトリ（デフォルトは build/）に以下が生成されます:

build/
├── index.html    # 全章を含む単一 HTML ファイル
└── images/       # コピーされた画像ファイル

5.3 確認方法

生成された index.html をブラウザで直接開くだけで閲覧できます。 Web サーバーは不要です:

# macOS の場合
open build/index.html

# Linux の場合
xdg-open build/index.html

5.4 動作確認のポイント

ビルド後に以下を確認してください:

• 目次: 左サイドバーに全章の見出しが表示されているか
• 章の切り替え: 目次をクリックして章が切り替わるか
• 検索: 検索窓にキーワードを入力して目次が絞り込まれるか
• パーマリンク: URL の # に章のスラッグが付き、リロードしても同じ章が表示されるか
• 画像: Markdown で参照した画像が正しく表示されるか

5.5 配布する

できあがった本を他の人に届けるのはとても簡単です。build/ ディレクトリの中身をそのまま渡すだけで構いません。

ligarb が生成する本は単一の HTML ファイルとアセットだけで完結しています。コードのシンタックスハイライトや Mermaid の図表、数式の描画に使われる JavaScript・CSS も build/ の中に含まれているため、受け取った人はインターネット接続がなくても index.html をブラウザで開くだけですべての内容を閲覧できます。

Web で公開したい場合も、build/ ディレクトリをそのまま GitHub Pages などの静的ホスティングに配置すれば、そのまま本として機能します。

なお、book.yml で ai_generated: true を設定して作成した本には、AI によって生成されたことを示すバッジや免責表示が自動的に付与されます。AI が生成した文章には事実と異なる内容が含まれる可能性があるため、配布前に内容を確認し、必要に応じて修正を行ってください。

発展編

この Part ではローカルサーバーでのプレビューやレビュー機能、AI を活用した執筆支援など、ligarb をより便利に使いこなすための機能を紹介します。

6. 多言語対応（Translations）

ligarb では、1 つの書籍プロジェクトから複数言語の HTML を生成できます。ハブとなる設定ファイルに多言語対応の定義を記述し、言語ごとの子設定ファイルで個別の内容を管理します。

6.1 ハブ設定ファイル

プロジェクトのルートに置く book.yml がハブの役割を果たします。ここに translations フィールドを記述し、言語コードと子設定ファイルのパスを対応付けます。

repository: "https://github.com/user/repo"
ai_generated: true
bibliography: references.bib
output_dir: "build"
translations:
  ja: book.ja.yml
  en: book.en.yml

translations の各キーは IETF 言語タグ（ja, en など）で、値は子設定ファイルへの相対パスです。

6.2 子設定ファイルと継承

各言語の子設定ファイル（book.ja.yml, book.en.yml など）は、inherit フィールドでハブの共通設定を継承します。

日本語版（book.ja.yml）:

inherit: book.yml
title: "マニュアル"
language: "ja"
output_dir: "build/ja"
chapters:
  - chapters/intro.md

英語版（book.en.yml）:

inherit: book.yml
title: "Manual"
language: "en"
output_dir: "build/en"
chapters:
  - chapters/en/intro.md

6.2.1 継承のルール

ハブに書いた共通設定（repository, bibliography, ai_generated 等）は子に自動で継承されます。子側で同じキーを指定すれば上書きできます。

ただし、output_dir は継承されません。ligarb build に渡した設定ファイル自身の output_dir が常に使われます。

6.2.2 言語ごとの必須フィールド

子設定ファイルでは以下のフィールドが必須です:

• title – 書籍タイトル（言語ごとに異なる）
• language – 言語コード
• chapters – 章ファイルのリスト

6.3 ビルド方法

ligarb build に渡すファイルによって、統合ビルドと単体ビルドを使い分けられます。

ligarb build book.yml       # ハブ → 全言語を1ファイルに統合
ligarb build book.ja.yml    # 日本語版のみ
ligarb build book.en.yml    # 英語版のみ

たとえば以下の設定の場合:

# book.yml       → output_dir: "build"
# book.ja.yml    → output_dir: "build/ja"
# book.en.yml    → output_dir: "build/en"

3 つすべてをビルドすると、次のように出力されます:

build/
├── index.html        # 統合版（言語切り替え付き）
├── ja/index.html     # 日本語のみ
└── en/index.html     # 英語のみ

統合ビルドでは、すべての言語のコンテンツが 1 つの index.html に含まれ、JavaScript による言語切り替えで表示を切り替えます。単体ビルドでは inherit 経由でハブの共通設定を引き継ぎつつ、指定した言語だけの HTML が生成されます。

6.4 言語切り替え UI

統合ビルドの出力では、サイドバーに言語切り替えボタンが表示されます。たとえば日本語と英語の 2 言語構成なら、EN | JA のようなボタンが並びます。

選択した言語は localStorage に保存され、次回アクセス時に自動で復元されます。

言語を切り替えると、同じ章の同じセクション位置に移動します。

6.5 ディレクトリ構成例

典型的な多言語プロジェクトのディレクトリ構成は次のようになります:

my-book/
├── book.yml          # ハブ（共通設定 + translations）
├── book.ja.yml       # 日本語版
├── book.en.yml       # 英語版
├── chapters/
│   ├── intro.md          # 日本語の章
│   └── en/
│       └── intro.md      # 英語の章
└── images/

画像などのアセットは言語間で共有できます。言語固有の画像が必要な場合は、images/ja/, images/en/ のようにサブディレクトリで分けることもできます。

7. プレビューとレビュー

7.1 ligarb serve — ローカルサーバー

ligarb serve コマンドで、ビルド済みの本をローカル Web サーバーで配信できます。 起動時に自動でビルドが実行されるため、事前に ligarb build を実行する必要はありません。

ligarb serve                    # http://localhost:3000 で配信
ligarb serve --port 8080        # ポート指定
ligarb serve path/to/book.yml   # book.yml のパスを指定

7.2 ライブリロード

ソースを編集して ligarb build を実行すると、ブラウザの右下にリロードボタンが表示されます。 クリックするとスクロール位置を維持したままコンテンツが更新されます。

Linux 環境では inotify を使って index.html の変更を即座に検知します。 その他の OS では 2 秒間隔のポーリングで検知します。

7.3 レビュー UI

ブラウザ上で本文にコメントを付け、Claude と議論し、承認した変更をソースファイルに反映できます。

7.3.1 コメントの流れ

1. テキスト選択: 本文中のテキストをドラッグで選択すると「Comment」ボタンが表示されます
2. コメント入力: ボタンをクリックするとサイドパネルが開き、コメントを入力できます
3. Claude レビュー: コメントを送信すると Claude（Opus）が book.yml を読み、必要に応じて全章や参考文献ファイルを参照して改善提案を返します。複数の章にまたがるパッチも生成できます
4. パッチ確認: メッセージ内の「Show patch」ボタンで、提案された変更の diff（赤=削除、緑=追加）を確認できます
5. 議論: 提案に対して返信し、さらに議論を続けることもできます

7.3.2 承認と却下

• Approve: パッチをソースファイルに適用し、自動でリビルドします。Claude を再度呼び出さないため即座に完了します
• Dismiss: スレッドを閉じます（変更は適用されません）

7.3.3 レビューの管理

右下のメールアイコン（✉）でレビュー一覧パネルを開けます。 未解決のスレッドがある場合、アイコンが黄色くハイライトされバッジに件数が表示されます。

パネルを閉じても処理中のレビューは中断されません。 一覧から該当スレッドをクリックすれば、いつでも会話を再開できます。

7.3.4 データの保存先

レビューデータは .ligarb/reviews/ ディレクトリに JSON ファイルとして保存されます。 .gitignore に追加するかどうかはプロジェクトに応じて判断してください。

.ligarb/
└── reviews/
    ├── 3f8a1b2c-...json
    └── 7d4e5f6a-...json

7.4 内部 API

サーバーは /_ligarb/ プレフィックスで内部 API を提供します。 フロントエンドの JS がこれらを使用しますが、外部ツールとの連携にも利用できます。

8. AI と一緒に使う

8.1 ligarb write — AI で本を自動生成

ligarb write コマンドを使うと、AI（Claude）に本を丸ごと書かせることができます。 企画書（brief.yml）を用意して実行するだけで、Markdown ファイルの生成からビルドまで自動で行います。

8.1.1 ワークフロー

ligarb write --init ruby_book    # ruby_book/brief.yml を生成
vi ruby_book/brief.yml           # 企画を編集
ligarb write ruby_book/brief.yml # ruby_book/ に本を生成 + ビルド
ligarb write --no-build          # 生成のみ（ビルドしない）

8.1.2 brief.yml の書き方

最小限はタイトルだけです:

title: "Git入門ガイド"

詳しく指定することもできます:

# brief.yml - 本の企画書
title: "Ruby入門"
language: ja
audience: "プログラミング初心者"
notes: |
  5章くらいで。
  コード例を多めにしてください。
  Railsには触れず、純粋なRubyに絞ってください。

notes に何でも書けるので、章数の希望、スタイルの指示、含めたい内容、除外したい内容などを自由に記述できます。

8.1.3 参照ファイル（sources）

sources を指定すると、AI がそのファイルを読んだ上で本を執筆します。既存の資料やメモをもとに本を書かせたいときに便利です:

title: "社内システム解説"
sources:
  - architecture.md
  - path: notes/meeting-2025-03.md
    label: "3月会議メモ"

文字列で指定するとファイル名がそのままラベルになります。path と label を個別に指定することもできます。パスは brief.yml からの相対パスです。

8.1.4 AI 生成コンテンツの表示

ligarb write で生成した本には、book.yml に ai_generated: true が自動で設定されます。これにより:

• サイドバーに「AI 生成」バッジが表示される
• 各章の末尾に注意喚起テキストが表示される
• 検索エンジンのインデックスと AI クローラーの学習を抑止するメタタグが追加される

フッターのテキストは footer フィールドでカスタマイズできます:

ai_generated: true
footer: "AI生成コンテンツです。内容を鵜呑みにしないでください。"

footer は ai_generated とは独立して使うこともできます（著作権表示など）。

8.1.5 前提条件

Claude Code の CLI（claude コマンド）がインストールされている必要があります。

8.2 手動で AI を使う

ligarb write を使わずに、手動で AI に指示することもできます。 ligarb help の出力を AI に渡してください:

ligarb help

この出力には設定ファイルの仕様、対応する Markdown 記法、利用可能なコードブロックの種類など、 AI が本を作るために必要な情報がすべて含まれています。

8.2.1 プロンプト例

新しい本を一から作る

ligarb help の出力を読んで、以下の本を作ってください:
- テーマ: Git 入門ガイド
- 対象者: プログラミング初心者
- 章構成: 5 章程度
- 言語: 日本語

ligarb init で雛形を作ってから、章を追加してください。

既存のドキュメントを本にする

このディレクトリにある Markdown ファイルを ligarb で本にまとめてください。
ligarb help を見て、book.yml を作り、ligarb build でビルドしてください。

図や数式を含む本を作る

ligarb help を読んで、以下の内容で本を作ってください。
mermaid でアーキテクチャ図を入れてください。

テーマ: Web アプリケーションの設計パターン

ligarb help を読んで、線形代数の入門書を作ってください。
数式は ```math（KaTeX）を使ってください。

章を追加・編集する

ligarb help を見て、この本に「デプロイ」の章を追加してください。
book.yml にも登録してください。

03-api.md の内容を見直して、シーケンス図（mermaid）を追加してください。

8.2.2 既存の本に翻訳を追加する

すでに日本語で書いた本を海外の読者にも届けたい、あるいは英語の技術ドキュメントに日本語版を追加したい場合があります。ligarb の多言語対応機能（6. 多言語対応（Translations） 参照）を使えば、1 つの HTML に複数言語を収めて言語切り替えで読み分けられます。

AI にこの作業を依頼するときは、既存の book.yml をハブに変換し、全章を翻訳するという手順を伝えてください。ligarb help に仕様が含まれているため、AI は translations、inherit などの設定を正しく扱えます。

日本語の本に英語版を追加する例:

ligarb help を読んで、この日本語の本に英語版を追加してください。

手順:
1. 既存の book.yml を translations ハブに変換
   - 共通設定（repository, bibliography 等）をハブに残す
   - 日本語固有の設定を book.ja.yml に分離（inherit: book.yml を付ける）
2. chapters/en/ に全章を英語に翻訳
3. book.en.yml を作成（inherit: book.yml）
4. ligarb build book.yml で統合ビルドして確認

英語の本に日本語版を追加する場合も同様です:

ligarb help を読んで、この英語の本に日本語版を追加してください。

手順:
1. 既存の book.yml を translations ハブに変換
   - 共通設定をハブに残す
   - 英語固有の設定を book.en.yml に分離（inherit: book.yml を付ける）
2. chapters/ja/ に全章を日本語に翻訳
3. book.ja.yml を作成（inherit: book.yml）
4. ligarb build book.yml で統合ビルドして確認

ビルドと確認

ligarb build でビルドしてください。エラーがあれば修正してください。

8.3 注意事項

8.4 ポイント

• ligarb write を使う: 企画書を書いて実行するだけで、本の生成からビルドまで自動化できます
• ligarb help を渡す: 手動で AI を使う場合、仕様を正確に理解させるための最も確実な方法です
• 図を指示する: 「mermaid で図を入れて」「KaTeX で数式を書いて」と明示すると、AI が適切なコードブロックを使います
• 段階的に進める: 一度にすべてを指示するより、章ごとに指示した方が品質が上がります

A. 設定リファレンス

A.1 book.yml フィールド一覧

A.2 chapters の構成要素

chapters 配列には、以下の 3 種類の要素を含めることができます:

A.2.1 章（文字列）

chapters:
  - 01-introduction.md
  - 02-getting-started.md

A.2.2 パート（part）

chapters:
  - part: part1.md
    chapters:
      - 01-introduction.md
      - 02-getting-started.md

part には Markdown ファイルを指定します。そのファイルの h1 がパートタイトル、本文が扉ページになります。

A.2.3 付録（appendix）

chapters:
  - appendix:
    - a1-references.md
    - a2-glossary.md

付録の章には数字ではなくアルファベット（A, B, C, …）で番号が付きます。

Basics

In this part, you will learn the fundamentals of creating a book with ligarb, from installation and project setup to writing in Markdown and building for review.

1. Introduction

1.1 What is ligarb?

ligarb is a CLI tool that generates a single HTML file from multiple Markdown files. It is ideal for organizing information in “book” format, such as software documentation and tutorials.

1.2 Features

1.2.1 Output

• Single HTML output: All chapters are combined into one index.html
• Searchable table of contents: A sidebar TOC with keyword filtering
• Chapter switching: JavaScript toggles content by chapter
• Permalink support: Link directly to a specific chapter via URL #
• Parts & appendices: Group chapters into parts and add appendices
• Previous/Next navigation: Links to adjacent chapters at the bottom of each chapter
• Dark mode: Toggle via a button in the sidebar
• Custom CSS: Apply your own styles
• GitHub edit links: Show “Edit on GitHub” links for each chapter
• Responsive design: Comfortable reading on both desktop and mobile
• Print support: All chapters are expanded when printing

1.2.2 Writing Assistance

• AI auto-writing: Write a brief (brief.yml) and run ligarb write to automate everything from generation to build
• Comment & review: Select text in ligarb serve to comment, and Claude will return improvement suggestions and patches. Approve to auto-apply to source files
• Manual AI integration: Pass the output of ligarb help to an AI for accurate spec-aware chapter editing

1.3 Comparison with Similar Tools

Several tools generate books from Markdown. Here is how ligarb compares to some popular ones.

1.3.1 mdBook

A Rust-based documentation generator used for the official Rust documentation. It generates multi-page output by default. ligarb combines all chapters into a single HTML, so you can share the entire book by passing a single file.

1.3.2 Honkit (formerly GitBook)

A Node.js-based open-source fork of GitBook. It can produce single-page output but requires a Node.js build environment. ligarb runs with just Ruby and a few gems, and configuration is a single book.yml.

1.3.3 Sphinx

A Python-based documentation generator supporting reStructuredText and Markdown. It is very feature-rich but has a steeper learning curve. ligarb prioritizes simplicity: “write in Markdown, build with one command.”

1.3.4 Pandoc

A universal format converter. It can generate a single HTML from multiple Markdown files, but features like a sidebar TOC, chapter switching, and search must be built separately. ligarb includes all of these out of the box.

1.3.5 VitePress

A Vue-based static site generator widely used for documentation sites. It offers a dev server with instant preview, Vue component embedding, and SEO-friendly multi-page output — features tailored for public-facing documentation sites. ligarb, on the other hand, specializes in single HTML output that requires no hosting and can be shared by simply passing a file. VitePress is the better choice for public documentation sites where SEO matters; ligarb is ideal for internal manuals and distributable books.

1.3.6 Where ligarb Fits

ligarb focuses on making it easy to create a book and distribute it as-is. Single HTML output, built-in sidebar TOC and search, and AI integration are available with minimal configuration. For highly customizable output formats and themes, Sphinx or mdBook may be better suited, but when you want to quickly turn your Markdown into a book, ligarb shines.

1.4 About This Manual

This manual itself is built with ligarb. The following chapters walk you through installation to building your first book.

2. Installation and Setup

2.1 Requirements

To use ligarb, you need:

• Ruby 3.0 or later
• Bundler (gem install bundler)

2.2 Installation

Clone the ligarb repository and install dependencies:

git clone https://github.com/ko1/ligarb.git
cd ligarb
bundle install

2.3 Checking the Help

Once installed, check the usage with the ligarb help command:

ligarb help

All commands and configuration options are displayed. Refer to this command first whenever you have questions.

2.4 Creating a Project

Create a book project with the following directory structure:

my-book/
├── book.yml
├── chapters/
│   ├── 01-first-chapter.md
│   └── 02-second-chapter.md
└── images/          # if you have images
    └── screenshot.png

book.yml is the configuration file, and Markdown files for each chapter go under chapters/.

3. Writing book.yml

3.1 Basic Structure

book.yml is a YAML configuration file. Here is the basic structure:

title: "Book Title"
author: "Author Name"
language: "en"
output_dir: "build"
chapters:
  - 01-introduction.md
  - 02-details.md

3.2 Field List

3.3 Specifying Chapters

chapters can list chapter file paths directly, or organize them into parts and appendices.

3.3.1 Cover Page

You can add a cover page at the beginning of the book. The cover is not shown in the table of contents and is the first page displayed when the book is opened:

chapters:
  - cover: cover.md
  - 01-introduction.md

3.3.2 Simple Structure

The simplest format lists chapters flat:

chapters:
  - 01-introduction.md
  - 02-getting-started.md
  - 03-advanced.md

3.3.3 Grouping with Parts

For books with many chapters, you can group them into parts:

chapters:
  - part: part1.md
    chapters:
      - 01-introduction.md
      - 02-getting-started.md
  - part: part2.md
    chapters:
      - 03-advanced.md
      - 04-tips.md

Specify a Markdown file for part. Its h1 becomes the part title, and the body becomes the title page.

3.3.4 Adding Appendices

You can add appendices at the end. Appendix chapters are numbered with letters (A, B, C, …):

chapters:
  - part: part1.md
    chapters:
      - 01-introduction.md
  - appendix:
    - a1-references.md
    - a2-glossary.md

3.3.5 File Naming Conventions

There are no strict rules for file names, but number-slug.md is recommended for easy management. The number-slug portion becomes the chapter identifier (slug) used in the URL #.

3.4 Custom CSS

Specify a CSS file with the style field. It is loaded after the default styles:

style: "custom.css"

Override CSS custom properties to change colors, fonts, etc.:

:root {
  --color-accent: #e63946;
  --sidebar-width: 320px;
}

3.5 GitHub Edit Links

Set the repository field to show “View on GitHub” links at the bottom of each chapter (GitHub edit links):

repository: "https://github.com/user/my-book"

3.6 AI-Generated Mark

Setting ai_generated to true has the following effects:

• Displays an “AI Generated” badge in the sidebar
• Automatically adds a disclaimer footer to each chapter
• Adds noindex / noai meta tags (suppresses search indexing and AI training)

ai_generated: true

3.7 Footer

Use the footer field to display text at the bottom of each chapter. It can also override the default ai_generated disclaimer:

footer: "(c) 2025 Author Name. All rights reserved."

3.8 Bibliography

Specify a bibliography data file with the bibliography field. Both YAML (.yml) and BibTeX (.bib) formats are supported:

bibliography: references.bib

See Markdown Syntax for detailed usage.

3.9 Source Files (sources)

The sources field specifies files for the AI to reference during AI writing (ligarb write). The contents are passed as context to the AI:

sources:
  - notes.md
  - path: data/research.pdf
    label: "Research Report"

A plain string uses the filename as the label. You can also specify path and label separately.

3.10 Multi-Language Support (translations / inherit)

The translations field manages multiple language versions of the same book. The inherit field inherits shared settings from a parent config.

# book.yml (hub)
repository: "https://github.com/user/repo"
translations:
  ja: book.ja.yml
  en: book.en.yml

# book.ja.yml (child)
inherit: book.yml
title: "Manual"
language: "ja"
chapters:
  - 01-intro.md

See 6. Multi-Language Support (Translations) for details.

4. Markdown Syntax and Images

4.1 Supported Markdown Syntax

ligarb supports GitHub Flavored Markdown (GFM^{[GitHub, 2017]}). Markdown is a lightweight markup language first published by John Gruber in 2004^{[John, 2004]}, and the following syntax is available.

4.1.1 Headings

Headings are written with #. h1 through h3 appear in the table of contents:

# Chapter Title (h1)
## Section (h2)
### Subsection (h3)

The first h1 in each file becomes the chapter title shown in the TOC.

4.1.2 Code Blocks

Wrap code with triple backticks to create a code block. Specifying a language name enables automatic syntax highlighting:

def greet(name)
  puts "Hello, #{name}!"
end

def fibonacci(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a

const fetchData = async (url) => {
  const response = await fetch(url);
  return response.json();
};

Syntax highlighting uses highlight.js^{[Ivan, 2011]}. It is automatically downloaded at build time only when language-specified code blocks are present in the Markdown.

4.1.3 Diagrams (Mermaid)

Use ` ```mermaid` to draw Mermaid diagrams. Flowcharts, sequence diagrams, class diagrams, and many more are supported.

Flowchart:

graph TD
    A[User] -->|Request| B[Web Server]
    B --> C{Authenticated?}
    C -->|Yes| D[Serve Content]
    C -->|No| E[Login Page]
    E -->|Authenticate| C

Sequence diagram:

sequenceDiagram
    participant U as User
    participant S as Server
    participant DB as Database
    U->>S: Send Request
    S->>DB: Execute Query
    DB-->>S: Return Results
    S-->>U: Response

Bar chart (xychart):

xychart
    title "Monthly Sales"
    x-axis ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
    y-axis "Sales ($K)" 0 --> 500
    bar [120, 230, 180, 350, 410, 300]
    line [120, 230, 180, 350, 410, 300]

Line chart (xychart, line only):

xychart
    title "Temperature"
    x-axis ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
    y-axis "Temp (C)" -5 --> 30
    line [2, 4, 10, 16, 22, 26]

Pie chart:

pie title Browser Share
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 4
    "Edge" : 4
    "Other" : 8

Gantt chart:

gantt
    title Project Plan
    dateFormat YYYY-MM-DD
    section Design
        Requirements      :a1, 2025-01-01, 14d
        Architecture      :a2, after a1, 10d
    section Development
        Implementation    :b1, after a2, 21d
        Testing           :b2, after b1, 14d

Mind map:

mindmap
    root((ligarb))
        Markdown
            GFM
            Code Blocks
            Math
        Build
            HTML Generation
            Asset Management
        Features
            TOC
            Index
            Bibliography

See the Mermaid documentation for detailed syntax.

4.1.4 Math (KaTeX)

Use ` ```math` for math rendering with KaTeX^{[Khan, 2014]}. Write equations in LaTeX^{[Leslie, 1994]} notation.

Quadratic formula:

Gaussian integral:

Matrix:

4.1.5 Function Plots (functionplot)

Use ` ```functionplot` to draw function graphs.

Write one function per line in the y = <expression> format:

Polar and parametric curves are also supported:

Options are specified as key: value:

• range / xrange – X-axis range (e.g., [-2pi, 2pi])
• yrange – Y-axis range
• width / height – Size in pixels (default: 600x400)
• title – Graph title
• grid: true – Show grid lines

These external libraries are automatically downloaded at build time only when the corresponding code blocks are present in the Markdown. They are placed in build/js/ and build/css/. Already-downloaded files are skipped.

4.1.6 Inline Math

Embed math in text by wrapping it with $...$. For example, the famous equation is written as:

The famous equation $E = mc^2$ is written as follows.

Complex expressions like the quadratic formula can also be written inline.

4.1.7 Tables

GFM table syntax is supported:

4.1.8 Lists

Both regular lists and task lists are supported:

• Item 1
• Item 2
  • Nesting is possible

1. Numbered list
2. Second item

4.1.9 Blockquotes

> This is a blockquote.
> It can span multiple lines.

4.1.10 Admonitions

GFM blockquote alert syntax creates styled admonition boxes:

The syntax is as follows:

> [!NOTE]
> Write supplemental information here.

> [!TIP]
> Write advice here.

> [!WARNING]
> Write cautions here.

> [!CAUTION]
> Write warnings about dangerous operations here.

> [!IMPORTANT]
> Write important information here.

Five types are supported: NOTE, TIP, WARNING, CAUTION, and IMPORTANT.

4.1.11 Footnotes

You can insert footnotes in the text¹. Multiple footnotes are also supported².

You can insert footnotes in the text[^1].

[^1]: This is the footnote content.

Footnote IDs are scoped per chapter, so the same number can be used in different chapters without collision.

4.2 Images

4.2.1 Directory

Place image files in the images/ directory:

my-book/
├── book.yml
├── chapters/
│   └── 01-introduction.md
└── images/
    ├── screenshot.png
    └── diagram.svg

4.2.2 Referencing in Markdown

Reference images with relative paths in Markdown:

![Screenshot](images/screenshot.png)

ligarb rewrites image paths to images/filename at build time and copies the contents of the images/ directory to the output.

4.2.3 Supported Formats

Common image formats such as PNG, JPEG, SVG, and GIF are supported. Images are copied as-is without conversion or optimization.

4.3 Index

An index can be automatically generated at the end of the book. Use Markdown link syntax to mark index terms.

4.3.1 Basic Usage

Specify #index as the link target, and the link text becomes the index term:

[Ruby](#index) is a dynamically typed language.

To use a different index term from the display text, use #index:term:

[dynamically typed language](#index:dynamic typing)

4.3.2 Multiple Index Terms

Register multiple index terms from a single location using commas:

[Ruby](#index:Ruby,Programming Languages/Ruby)

4.3.3 Hierarchical Index

Use / to create hierarchical index entries. For example, Programming Languages/Ruby produces:

Programming Languages
  Ruby ......... Chapter 4

4.3.4 Example

Here are examples of index markers used in this manual:

Markdown is a lightweight markup language. highlight.js provides syntax highlighting, Mermaid provides diagrams, and KaTeX provides math rendering.

Index markers are displayed as plain text without link styling. An “Index” section is automatically added at the end of the book.

4.4 Bibliography

You can cite references in the text and automatically generate a bibliography list at the end of the book.

4.4.1 Setup

Specify a bibliography data file in book.yml. The format is auto-detected by file extension:

bibliography: references.yml   # YAML format
bibliography: references.bib   # BibTeX format

YAML Format

A mapping of keys to reference data:

matz1995:
  author: "Yukihiro Matsumoto"
  title: "The Ruby Programming Language"
  year: 1995
  url: "https://www.ruby-lang.org"
  publisher: "O'Reilly"

BibTeX Format (.bib)

Standard BibTeX notation:

@book{matz1995,
  author = {Yukihiro Matsumoto},
  title = {The Ruby Programming Language},
  year = {1995},
  publisher = {O'Reilly},
  url = {https://www.ruby-lang.org}
}

@article{knuth1984,
  author = {Donald Knuth},
  title = {Literate Programming},
  year = {1984},
  journal = {The Computer Journal},
  volume = {27},
  number = {2},
  pages = {97-111}
}

BibTeX notes:

• Lines starting with % are treated as comments
• Field values are enclosed in {...} or "..."
• One level of nested braces is supported (e.g., {The {Ruby} Language})
• Entry types (@book, @article, etc.) affect the display format

4.4.2 Supported Fields

The following fields are available for both YAML and BibTeX:

4.4.3 Display by Entry Type

The bibliography list format varies by BibTeX entry type:

• book: Author. Title. Edition. Publisher. Year.
• article: Author. “Title”. Journal, Volume(Number), pp. Pages. Year.
• inproceedings: Author. “Title”. In Booktitle, pp. Pages. Year.
• other/YAML: Author. Title. Publisher. Journal. Volume. Pages. Year.

4.4.4 Citing References

Specify #cite:key as the link target:

[Ruby](#cite:matz1995) is a wonderful language.

This renders as “Ruby^{[Yukihiro, 1995]} is a wonderful language.” The superscript [author, year] is a link to the bibliography section, and hovering shows the full reference information.

4.4.5 Example

This manual itself uses the bibliography feature. References are defined in BibTeX format in manual/references.bib and cited throughout the text.

Markdown^{[John, 2004]} is a lightweight markup language published in 2004. GitHub later extended it as GFM^{[GitHub, 2017]}, adding features like tables and task lists. Math rendering uses KaTeX^{[Khan, 2014]}, and syntax highlighting uses highlight.js^{[Ivan, 2011]}. The math notation is based on Lamport’s LaTeX^{[Leslie, 1994]}, and the fusion of documentation and executable code via code blocks is influenced by Knuth’s Literate Programming^{[Donald, 1984]}. Cross-referencing via hyperlinks is a fundamental concept of Berners-Lee et al.’s WWW^{[Tim, 1992]}.

The source of the above example looks like this:

[Markdown](#cite:gruber2004) is a lightweight markup language...
[Knuth's Literate Programming](#cite:knuth1984) is influenced by...
[Berners-Lee et al.'s WWW](#cite:berners-lee1992) is a fundamental concept.

4.4.6 Behavior Details

• The bibliography section is automatically added before the index
• References are sorted by author name and year
• If url is present, the title becomes a link
• If doi is present, a DOI link is appended
• Referencing a non-existent key with #cite: outputs a warning and displays [key?] in red (the build is not interrupted)
• If bibliography is not configured, the bibliography section is not generated

4.5 Cross-References

You can create links to other chapters or headings using standard Markdown link syntax. At build time, relative links to .md files are converted to anchors within the single HTML.

4.5.1 Basic Usage

Cross-references are written as standard Markdown links. Specifying a .md file as the link target resolves it automatically at build time:

[Configuration details](03-book-yml.md)

To link to a specific heading, add a # fragment:

[chapters field](03-book-yml.md#Specifying Chapters)

4.5.2 Auto-Filled Link Text

Leaving the link text empty auto-fills it with the target’s chapter title or heading text (with numbering):

See [](03-book-yml.md) for details.
Configuration is explained in [](03-book-yml.md#Specifying Chapters).

In the above example, the link text is filled with something like “3. Writing book.yml” and “3.1 Specifying Chapters” with chapter/section numbers.

4.5.3 Path Resolution

The .md path is resolved relative to the current Markdown file’s directory. Files in the same directory can be referenced by filename alone.

4.5.4 Error Detection

If the referenced chapter file or heading does not exist, the build fails with an error:

Error: cross-reference target not found: missing.md (from 01-introduction.md)
Error: cross-reference heading not found: 03-book-yml.md#typo (from 04-markdown.md)

5. Building and Reviewing

5.1 Build Command

Run the following in your book project directory (ligarb build):

ligarb build

If book.yml is in a different location, specify the path:

ligarb build path/to/book.yml

5.2 Output

When the build succeeds, the following is generated in the directory specified by output_dir (default: build/):

build/
├── index.html    # Single HTML file containing all chapters
└── images/       # Copied image files

5.3 Viewing

Simply open the generated index.html in a browser. No web server is required:

# macOS
open build/index.html

# Linux
xdg-open build/index.html

5.4 Verification Checklist

After building, verify the following:

• Table of contents: Are all chapter headings displayed in the left sidebar?
• Chapter switching: Do chapters switch when clicking TOC items?
• Search: Does typing keywords in the search box filter the TOC?
• Permalinks: Does the URL # contain the chapter slug, and does reloading show the same chapter?
• Images: Are images referenced in Markdown displayed correctly?

5.5 Distribution

Distributing your finished book is very simple. Just share the contents of the build/ directory.

Books generated by ligarb are self-contained with a single HTML file and assets. JavaScript and CSS for syntax highlighting, Mermaid diagrams, and math rendering are all included in build/, so recipients can view the entire book by opening index.html in a browser – even without an internet connection.

For web publishing, simply deploy the build/ directory to a static hosting service like GitHub Pages, and it works as a book immediately.

Note that books created with ai_generated: true in book.yml automatically include a badge and disclaimer indicating AI-generated content. Since AI-generated text may contain inaccuracies, please review and correct the content before distribution.

Advanced

In this part, we introduce features that help you get more out of ligarb, including local server preview, review functionality, and AI-powered writing assistance.

6. Multi-Language Support (Translations)

ligarb can generate HTML output in multiple languages from a single book project. You define translations in a hub configuration file and manage per-language content through child configuration files.

6.1 Hub Configuration File

The book.yml at the project root serves as the hub. It contains the translations field, which maps language codes to child configuration files.

repository: "https://github.com/user/repo"
ai_generated: true
bibliography: references.bib
output_dir: "build"
translations:
  ja: book.ja.yml
  en: book.en.yml

Each key under translations is an IETF language tag (ja, en, etc.), and the value is a relative path to the child configuration file.

6.2 Child Configuration Files and Inheritance

Each language’s child configuration file (book.ja.yml, book.en.yml, etc.) uses the inherit field to inherit shared settings from the hub.

Japanese version (book.ja.yml):

inherit: book.yml
title: "マニュアル"
language: "ja"
output_dir: "build/ja"
chapters:
  - chapters/01-intro.md

English version (book.en.yml):

inherit: book.yml
title: "Manual"
language: "en"
output_dir: "build/en"
chapters:
  - chapters/en/01-intro.md

6.2.1 Inheritance Rules

Shared settings written in the hub (repository, bibliography, ai_generated, etc.) are automatically inherited by child files. A child can override any inherited key by specifying it directly.

However, output_dir is not inherited. The output_dir of whichever config file is passed to ligarb build is always used.

6.2.2 Required Fields per Language

The following fields are required in each child configuration file:

• title – The book title (different for each language)
• language – The language code
• chapters – The list of chapter files

6.3 Building

You can produce an integrated build or standalone per-language builds depending on which file you pass to ligarb build.

ligarb build book.yml       # Hub: all languages in one file
ligarb build book.ja.yml    # Japanese only
ligarb build book.en.yml    # English only

For example, given these settings:

# book.yml       → output_dir: "build"
# book.ja.yml    → output_dir: "build/ja"
# book.en.yml    → output_dir: "build/en"

Building all three produces:

build/
├── index.html        # Integrated (with language switcher)
├── ja/index.html     # Japanese only
└── en/index.html     # English only

The integrated build includes content for all languages in a single index.html, with a JavaScript-based language switcher to toggle the display. Standalone builds inherit shared settings from the hub via inherit, but generate HTML for the specified language only.

6.4 Language Switcher UI

In the integrated build output, the sidebar displays language switcher buttons. For example, with a Japanese and English configuration, buttons like EN | JA appear.

The selected language is stored in localStorage and automatically restored on the next visit.

6.5 Directory Structure Example

A typical multi-language project directory looks like this:

my-book/
├── book.yml          # Hub (shared settings + translations)
├── book.ja.yml       # Japanese version
├── book.en.yml       # English version
├── chapters/
│   ├── 01-intro.md       # Japanese chapters
│   └── en/
│       └── 01-intro.md   # English chapters
└── images/

Assets such as images can be shared across languages. If language-specific images are needed, you can organize them into subdirectories like images/ja/ and images/en/.

7. Preview and Review

7.1 ligarb serve – Local Server

The ligarb serve command serves the built book via a local web server. A build is automatically run at startup, so there is no need to run ligarb build beforehand.

ligarb serve                    # Serve at http://localhost:3000
ligarb serve --port 8080        # Specify port
ligarb serve path/to/book.yml   # Specify book.yml path

7.2 Live Reload

When you edit the source and run ligarb build, a reload button appears in the bottom-right corner of the browser. Clicking it updates the content while preserving the scroll position.

On Linux, inotify is used to detect changes to index.html immediately. On other operating systems, changes are detected via 2-second interval polling.

7.3 Review UI

You can add comments to the book text in the browser, discuss with Claude, and apply approved changes to the source files.

7.3.1 Comment Flow

1. Text selection: Drag to select text in the book content, and a “Comment” button appears
2. Comment input: Click the button to open a side panel for entering your comment
3. Claude review: Submitting a comment triggers Claude (Opus) to read book.yml and reference all chapters and bibliography files as needed, returning improvement suggestions. Patches spanning multiple chapters can also be generated
4. Patch review: Use the “Show patch” button in the message to view the proposed changes as a diff (red = deletion, green = addition)
5. Discussion: Reply to the suggestion to continue the discussion

7.3.2 Approve and Dismiss

• Approve: Applies the patch to source files and triggers an automatic rebuild. Claude is not called again, so this completes instantly
• Dismiss: Closes the thread (no changes are applied)

7.3.3 Managing Reviews

Click the mail icon in the bottom-right corner to open the review list panel. When there are unresolved threads, the icon is highlighted in yellow with a badge showing the count.

Reviews in progress are not interrupted when the panel is closed. Click a thread in the list to resume the conversation at any time.

7.3.4 Data Storage

Review data is saved as JSON files in the .ligarb/reviews/ directory. Decide whether to add it to .gitignore based on your project needs.

.ligarb/
└── reviews/
    ├── 3f8a1b2c-...json
    └── 7d4e5f6a-...json

7.4 Internal API

The server provides an internal API under the /_ligarb/ prefix. The frontend JS uses these, but they can also be used for integration with external tools.

8. Using AI

8.1 ligarb write – Auto-Generate a Book with AI

The ligarb write command lets AI (Claude) write an entire book. Prepare a brief (brief.yml) and run the command to automate everything from Markdown generation to building.

8.1.1 Workflow

ligarb write --init ruby_book    # Generate ruby_book/brief.yml
vi ruby_book/brief.yml           # Edit the brief
ligarb write ruby_book/brief.yml # Generate book in ruby_book/ + build
ligarb write --no-build          # Generate only (skip build)

8.1.2 Writing brief.yml

The minimum is just a title:

title: "Git Getting Started Guide"

You can specify more details:

# brief.yml - Book brief
title: "Ruby for Beginners"
language: en
audience: "Programming beginners"
notes: |
  About 5 chapters.
  Include plenty of code examples.
  Focus on pure Ruby, no Rails.

You can write anything in notes, including desired number of chapters, style instructions, content to include or exclude, etc.

8.1.3 Reference Files (sources)

Specifying sources lets the AI read those files before writing the book. This is useful when you want the book based on existing materials or notes:

title: "Internal System Documentation"
sources:
  - architecture.md
  - path: notes/meeting-2025-03.md
    label: "March Meeting Notes"

A plain string uses the filename as the label. You can also specify path and label separately. Paths are relative to brief.yml.

8.1.4 AI-Generated Content Display

Books generated with ligarb write automatically have ai_generated: true set in book.yml. This means:

• An “AI Generated” badge is displayed in the sidebar
• A disclaimer text is shown at the bottom of each chapter
• Meta tags are added to suppress search engine indexing and AI crawler training

The footer text can be customized with the footer field:

ai_generated: true
footer: "AI-generated content. Please verify before relying on it."

footer can also be used independently of ai_generated (e.g., for copyright notices).

8.1.5 Prerequisites

The Claude Code CLI (claude command) must be installed.

8.2 Using AI Manually

You can also instruct AI manually without using ligarb write. Pass the output of ligarb help to the AI:

ligarb help

This output contains everything the AI needs to create a book: configuration file specs, supported Markdown syntax, available code block types, and more.

8.2.1 Prompt Examples

Create a new book from scratch

Read the output of ligarb help and create the following book:
- Topic: Git Getting Started Guide
- Audience: Programming beginners
- Structure: About 5 chapters
- Language: English

Use ligarb init to create a scaffold, then add chapters.

Turn existing documents into a book

Combine the Markdown files in this directory into a book using ligarb.
Read ligarb help, create book.yml, and build with ligarb build.

Create a book with diagrams and math

Read ligarb help and create a book with the following content.
Include architecture diagrams using mermaid.

Topic: Web Application Design Patterns

Read ligarb help and create an introduction to linear algebra.
Use ```math (KaTeX) for equations.

Add or edit chapters

Read ligarb help and add a "Deployment" chapter to this book.
Register it in book.yml as well.

Review the content of 03-api.md and add sequence diagrams (mermaid).

8.2.2 Add a translation to an existing book

Sometimes you want to make an English book available to Japanese readers, or add an English version to a Japanese technical document. ligarb’s multi-language feature (6. Multi-Language Support (Translations)) lets you bundle multiple languages into a single HTML with a language switcher.

When asking the AI to do this, tell it to convert the existing book.yml into a hub and translate all chapters. Since ligarb help includes the spec, the AI can correctly handle translations, inherit, and other settings.

Adding Japanese to an English book:

Read ligarb help and add a Japanese translation to this English book.

Steps:
1. Convert the existing book.yml into a translations hub
   - Keep shared settings (repository, bibliography, etc.) in the hub
   - Move English-specific settings to book.en.yml (add inherit: book.yml)
2. Translate all chapters into Japanese under chapters/ja/
3. Create book.ja.yml (with inherit: book.yml)
4. Build with ligarb build book.yml and verify

Adding English to a Japanese book follows the same approach:

Read ligarb help and add an English translation to this Japanese book.

Steps:
1. Convert the existing book.yml into a translations hub
   - Keep shared settings in the hub
   - Move Japanese-specific settings to book.ja.yml (add inherit: book.yml)
2. Translate all chapters into English under chapters/en/
3. Create book.en.yml (with inherit: book.yml)
4. Build with ligarb build book.yml and verify

Build and verify

Build with ligarb build. Fix any errors.

8.3 Important Notes

8.4 Key Points

• Use ligarb write: Write a brief and run it to automate everything from generation to build
• Pass ligarb help: When using AI manually, this is the most reliable way to make it understand the spec
• Request diagrams: Explicitly asking for “mermaid diagrams” or “KaTeX equations” helps the AI use the appropriate code blocks
• Work incrementally: Instructing chapter by chapter yields better quality than doing everything at once

A. Configuration Reference

A.1 book.yml Field List

A.2 chapters Elements

The chapters array can contain the following 3 types of elements:

A.2.1 Chapter (string)

chapters:
  - 01-introduction.md
  - 02-getting-started.md

A.2.2 Part

chapters:
  - part: part1.md
    chapters:
      - 01-introduction.md
      - 02-getting-started.md

Specify a Markdown file for part. Its h1 becomes the part title, and the body becomes the title page.

A.2.3 Appendix

chapters:
  - appendix:
    - a1-references.md
    - a2-glossary.md

Appendix chapters are numbered with letters (A, B, C, …) instead of numbers.