ligarb 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10e90698ccef79745b7709265f5657df0354c86000ef85be7401b56cb443da0b
-  data.tar.gz: 5edf902c6f4d06b0fe923f5eb24372b33379bfb50296cadeec04ef308c0cc217
+  metadata.gz: 4ba0a513e610d71f30b92bf61b42e2acdab5516e6105b56a43603692c60a3a9a
+  data.tar.gz: 5824b715da62d8d568d597a2edc0dc9a85dc0b7b7ef028499d7ce9cbcb65d161
 SHA512:
-  metadata.gz: c2d201101b94c3b63405599c21e91c043ac98967fbf6b25035a0e959782c70fbbfa9948981caac86cdb9f25405ebe0e8f2d80c5e5bab6453912a62f1c212cf24
-  data.tar.gz: ed28454394317ade969c4fd8e5dd974b3f34e732208f7089a5f603160a9e9f5172c78d11ef04f872d3b455de18811a56501b9e69e6983ce4d38942bae93d77d4
+  metadata.gz: c58b836062f00ef965e59f44fef837fe0551d22a57f93f957b0a25d718b18ef79447b11b50f8c4a52540fec9d96656397266d4500ecacc60e42faa474099abd3
+  data.tar.gz: f74f174bc842665f9d68387381cd92cfc9ee48745f1bf339d3f6393e96b17a7ddec0adbd561f8e56cfc92fd6a6b9eac6d3b102e4abc1e9f071407baa7870bbd2

data/assets/mermaid_check.mjs

@@ -2,11 +2,19 @@
 //
 // Usage: node mermaid_check.mjs <path/to/mermaid.min.js>
 //   stdin:  JSON array of {"id": <any>, "text": <mermaid source>}
-//   stdout: JSON array of {"id": <any>, "error": <message or null>}
+//   stdout: JSON array of {"id": <any>, "error": <message or null>,
+//                          "kind": "syntax" | "environment"}
 //
 // Loads the browser UMD bundle of mermaid in Node by stubbing just enough
 // of the DOM (mermaid.parse() only parses; it never renders, but DOMPurify
 // refuses to initialize without something that looks like a document).
+//
+// The DOM stub is intentionally minimal, so it cannot satisfy DOMPurify when a
+// node label contains HTML (e.g. "A[1<br>2]"): sanitizing real markup needs a
+// real DOM tree to walk, which the stub does not provide. That surfaces as a
+// generic JS error (e.g. TypeError "Right-hand side of 'instanceof'..."), NOT a
+// diagram syntax error. classifyError() tells the two apart so callers only
+// warn about genuine mermaid problems and not these harness limitations.
 
 const noop = () => {};
 
@@ -39,7 +47,11 @@ function makeStub(name, overrides = {}) {
 globalThis.window = globalThis;
 // nodeType 9 = DOCUMENT_NODE; DOMPurify checks it to decide it has a real DOM.
 globalThis.document = makeStub("document", { nodeType: 9 });
-globalThis.navigator = { userAgent: "node" };
+// Node >= 21 ships a built-in read-only `navigator` global; assigning to it
+// throws a TypeError. Only define our stub when the runtime lacks one.
+if (!("navigator" in globalThis)) {
+  globalThis.navigator = { userAgent: "node" };
+}
 globalThis.addEventListener = noop;
 globalThis.location = { href: "http://localhost/", protocol: "http:" };
 globalThis.Element = function Element() {};
@@ -73,14 +85,36 @@ if (!mermaid || typeof mermaid.parse !== "function") {
   process.exit(2);
 }
 
+// Decide whether a thrown error is a genuine mermaid diagram problem
+// ("syntax") or an artifact of our minimal DOM stub ("environment").
+//
+//   - jison grammar errors carry a structured `.hash`  -> syntax
+//   - mermaid's typed errors (e.g. UnknownDiagramError) -> syntax
+//   - generic JS runtime errors (TypeError/ReferenceError/RangeError/EvalError)
+//     with no hash come from the DOM stub                -> environment
+//   - anything else is reported as syntax, erring toward visibility
+function classifyError(e) {
+  if (e && e.hash !== undefined) return "syntax";
+  const name = e && e.name;
+  if (name && name.endsWith("DiagramError")) return "syntax";
+  if (["TypeError", "ReferenceError", "RangeError", "EvalError"].includes(name)) {
+    return "environment";
+  }
+  return "syntax";
+}
+
 const blocks = JSON.parse(readFileSync(0, "utf8"));
 const results = [];
 for (const block of blocks) {
   try {
     await mermaid.parse(block.text);
-    results.push({ id: block.id, error: null });
+    results.push({ id: block.id, error: null, kind: "syntax" });
   } catch (e) {
-    results.push({ id: block.id, error: String(e && e.message ? e.message : e) });
+    results.push({
+      id: block.id,
+      error: String(e && e.message ? e.message : e),
+      kind: classifyError(e),
+    });
   }
 }
 console.log(JSON.stringify(results));

data/assets/style.css

@@ -77,6 +77,22 @@ body {
   opacity: 1;
 }
 
+.ai-md-hint {
+  margin: 0 0 1.5rem;
+  font-size: 0.8rem;
+  color: var(--color-text-muted);
+  opacity: 0.8;
+}
+
+.ai-md-hint a {
+  color: inherit;
+  text-decoration: underline;
+}
+
+@media print {
+  .ai-md-hint { display: none; }
+}
+
 .book-title {
   font-size: 1.1rem;
   font-weight: 700;

data/docs/help.md

@@ -0,0 +1,868 @@
+# ligarb - Generate a single-page HTML book from Markdown files
+
+## Overview
+
+ligarb converts multiple Markdown files into a self-contained index.html.
+The generated HTML includes:
+- A left sidebar with a searchable table of contents (h1-h3)
+- Chapter-based content switching in the main area
+- Permalink support via URL hash (#chapter-slug)
+- Responsive design with print-friendly styles
+- Syntax-highlighted code blocks
+- Search with content highlighting
+- Chapter and section numbering (configurable)
+- Previous/Next chapter navigation
+- Dark mode toggle (saved to localStorage)
+- Custom CSS support
+- "Edit on GitHub" links (optional)
+- Footnotes (kramdown syntax)
+
+**Intended use:** ligarb is a local CLI tool for authors who build books from
+their own Markdown sources. The generated HTML is a static file meant to be
+opened in a browser or deployed to a static hosting service. `ligarb serve`
+is for local preview only and must not be exposed to the internet.
+
+**Non-goals:** ligarb does not sanitize Markdown-derived HTML, CSS, or
+bibliography URLs. It is not designed for untrusted third-party content,
+public upload services, or automated pipelines that ingest unreviewed input.
+If such use cases are needed, add HTML sanitization, URL validation, and CSP
+headers externally.
+
+## Commands
+
+### `ligarb init [DIRECTORY]`
+
+Create a new book project with scaffolding.
+If DIRECTORY is given, creates and populates that directory.
+If omitted, populates the current directory.
+Generates book.yml, 01-introduction.md, and images/.
+If .md files already exist, registers them as chapters.
+Aborts if book.yml already exists.
+
+### `ligarb setup-github-review [DIRECTORY] [--owner NAME]`
+
+Set up a GitHub-based review workflow in an existing project (book.yml must
+exist). DIRECTORY defaults to the current directory. Composable: run it after
+`ligarb init` or `ligarb write`, or on any hand-made project.
+
+It generates `.github/`, `SETUP.md`, and `SETUP.sh` — GitHub Actions workflows
+for publishing the book to GitHub Pages, checking that PRs still build, and
+(opt-in) letting Claude triage reader-filed issues into pull requests — plus
+issue forms for structured feedback and a gh CLI one-shot script (`SETUP.sh`)
+that does the repo creation / secret / Pages / labels setup. It also:
+- adds `github_review.enabled: true` to book.yml (the reader feedback UI) if
+  absent;
+- seeds a default `repository:` (`https://github.com/<owner>/<dir>`) if absent,
+  so the templates and SETUP.sh get concrete values — edit it if the guess is
+  wrong and re-run. `<owner>` is the `--owner` (alias `--user`) flag when given
+  — useful for an organization — otherwise `$USER`. If `repository:` is already
+  set, passing `--owner` is an error (edit `repository:` in book.yml directly);
+- seeds a default `site_url:` (the GitHub Pages URL derived from `repository`)
+  if absent, so the build emits `og:url`/canonical — edit it for a custom domain;
+- creates a project `README.md` linking to the GitHub Pages site, unless one
+  already exists (your README is never overwritten).
+
+Re-run it any time to update the scaffolding to the latest templates (e.g. after
+upgrading ligarb): existing generated files are **overwritten**, so review the
+changes with `git diff` and revert any local edits you want to keep. Your
+book.yml is never overwritten. `__OWNER__` / `__REPO__` placeholders in the
+templates are filled from book.yml's `repository:`; if it is unset the
+placeholders are left as-is (and the Discussions link in
+`.github/ISSUE_TEMPLATE/config.yml` is commented out). The generated files are
+the only thing that depends on Claude or GitHub Actions — ligarb itself never
+calls either at runtime. Read the generated `SETUP.md` for the manual steps
+(token registration, repository settings) that cannot be generated; it includes
+a gh CLI quickstart.
+
+### `ligarb build [CONFIG]`
+
+Build the HTML book.
+CONFIG defaults to 'book.yml' in the current directory.
+
+The output directory contains index.html plus js/ and css/ subdirectories
+for auto-downloaded libraries (highlight.js, mermaid, KaTeX, etc.).
+Open index.html directly in a browser — no web server needed.
+
+The build also emits a Markdown full-text version of the book next to
+index.html, intended for AI/LLM readers (HTML is noisy and costly to read;
+clean Markdown is cheaper and more faithful). For a single-language build it
+is `index.md`; for a multi-language (hub) build it is `index.<lang>.md` per
+language. Each is the concatenated chapter sources in reading order. The HTML
+points to it two ways: a small visible note at the top of the content ("For
+AI/LLM readers: a clean Markdown full-text version of this book is at …") and
+a `<link rel="alternate" type="text/markdown">` in the head. Both use a
+relative href (the bare filename), so they resolve against whatever URL the
+page is actually served from — local preview, staging, or production — rather
+than hard-coding `site_url` (the absolute canonical URL still lives in
+`og:url` / `<link rel="canonical">`). A fetcher resolves it against the page's
+own URL, so a model that fetched the page finds the bundle next to it. No tool
+is guaranteed to honor these automatically —
+the visible note is what actually reaches a model that fetched the page,
+since the in-page text is included in what the fetcher hands to the model.
+
+When `github_review.enabled` is true and `repository` is set (see
+Configuration below), the build also injects a static "Report as issue"
+feedback UI: readers select text, pick a type and add a comment, and a
+prefilled GitHub Issue form opens in a new tab (chapter/section, quoted text,
+source path, and current page URL are filled in). It is pure client-side JS
+with no backend or tokens — it only builds a URL and opens it. If
+`github_review.enabled` is true but `repository` is unset, build prints a
+warning and skips the UI. Without `github_review`, nothing is injected.
+
+### `ligarb serve [CONFIG...]`
+
+Start a local web server with live reload and review UI.
+CONFIG defaults to 'book.yml' in the current directory.
+Multiple CONFIG paths can be given to serve multiple books.
+
+Options:
+- `--port PORT` — Server port (default: 3000)
+- `--host ADDR` — Bind address (default: 127.0.0.1, loopback only).
+  Use `0.0.0.0` (or a specific LAN IP) to reach the server from other
+  devices — e.g. from the Windows host when running under WSL, or a
+  phone on the same network. Binding beyond loopback prints a warning:
+  the review/feedback APIs (file writes, Claude runs) become reachable
+  by other hosts, so only do this on a trusted network. Same-origin
+  protection still applies (POSTs must come from the page's own origin).
+- `--multi` — Force multi-book mode (even with 1 CONFIG)
+
+**Single book mode** (1 CONFIG, without --multi):
+- Serves the built HTML book at http://localhost:PORT
+
+**Multi-book mode** (2+ CONFIGs, or --multi):
+- Top page (/) shows a book index with links
+- Each book is served at /\<directory-name\>/
+- "Write a new book" button on the index page to generate
+  a new book via AI (posts a brief, runs Writer in background)
+- Example: `ligarb serve */book.yml`
+
+Features:
+- Injects a reload button that pulses when build output changes
+- Injects a review UI for commenting on book text
+- Review comments are saved to .ligarb/reviews/\*.json
+  (in each book's directory)
+- If 'claude' CLI is installed, comments are sent to Claude
+  for review suggestions, and approved changes are applied
+  to the source Markdown files and the book is rebuilt
+- Review patches can span multiple chapters and the
+  bibliography file (Claude reads book.yml to find all files)
+
+### `ligarb librarium`
+
+Start a multi-book library server.
+Automatically discovers \*/book.yml in the current directory.
+Equivalent to: `ligarb serve --multi */book.yml`
+
+Options:
+- `--port PORT` — Server port (default: 3000)
+- `--host ADDR` — Bind address (default: 127.0.0.1; see `serve` above)
+
+### `ligarb write [BRIEF]`
+
+Generate a complete book using AI (Claude).
+BRIEF defaults to 'brief.yml' in the current directory.
+Reads the brief, sends a prompt to Claude, and builds
+the generated book. Files are created in the same
+directory as brief.yml.
+
+- `ligarb write --init [DIR]` — Create a brief.yml template.
+  If DIR is given, creates DIR/brief.yml (mkdir as needed).
+  If omitted, creates brief.yml in the current directory.
+- `ligarb write --no-build` — Generate files only, skip the build step.
+
+Requires the 'claude' CLI to be installed.
+See the "Write Command" section below for brief.yml details.
+
+### `ligarb help`
+
+Show this detailed specification.
+
+### `ligarb --help`
+
+Show short usage summary.
+
+### `ligarb version`
+
+Show the version number.
+
+## Configuration: book.yml
+
+The configuration file is a YAML file with the following fields:
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `title` | required | — | The book title displayed in the header and \<title\> tag. |
+| `description` | optional | — | Short description for the `<meta name="description">` and Open Graph (`og:description`) tags. When omitted, it is auto-extracted from the first prose paragraph of the cover (or first) chapter. Not inherited by translations — set it per language. |
+| `site_url` | optional | — | Canonical published URL of the book. When set, emits `og:url` and `<link rel="canonical">`. Used verbatim, so set it to where this build is actually served. `setup-github-review` seeds it from `repository` (the GitHub Pages URL) if absent; edit it for custom domains or other hosting. |
+| `author` | optional | empty | Author name displayed in the header. |
+| `language` | optional | `"en"` | HTML lang attribute value. |
+| `output_dir` | optional | `"build"` | Output directory relative to book.yml. |
+| `chapter_numbers` | optional | `true` | Show chapter/section numbers (e.g. "1.", "1.1", "1.1.1"). |
+| `style` | optional | — | Path to a custom CSS file relative to book.yml. Loaded after the default styles, so it can override any rule. |
+| `repository` | optional | — | GitHub repository URL (e.g. "https://github.com/user/repo"). When set, each chapter shows a "View on GitHub" link pointing to `{repository}/blob/HEAD/{path-from-git-root}`. |
+| `ai_generated` | optional | `false` | Mark the book as AI-generated content. When true: adds an "AI Generated" badge in the sidebar header, adds a default disclaimer footer to each chapter, and adds noindex/noai meta tags. The footer text can be overridden with the `footer` field. |
+| `footer` | optional | — | Custom text displayed at the bottom of each chapter. Overrides the default ai_generated disclaimer if both are set. |
+| `bibliography` | optional | — | Path to a bibliography file (.yml or .bib) relative to book.yml. See "Bibliography" section. |
+| `sources` | optional | — | Reference files for AI context. Array of strings or `{path:, label:}` objects. Used by the `write` command and review AI. |
+| `github_review` | optional | — | A mapping enabling the static reader feedback UI. `enabled: true` injects a "Report as issue" UI into `build` output (requires `repository`). Optional sub-keys: `issue_template` (default `book-feedback.yml`) and `labels` (default `[feedback]`) prefilled into the GitHub Issue URL. Usually set by `ligarb setup-github-review`. |
+| `translations` | optional | — | A mapping of language codes to config file paths. Enables multi-language support. See "Translations" section. |
+| `inherit` | optional | — | Path to a parent config file. Inheritable settings (author, language, style, etc.) are loaded as defaults. Used by per-language configs for standalone builds. |
+| `chapters` | required | — | Book structure. An array that can contain: a cover, chapter strings, parts, and appendix. |
+
+### chapters array
+
+All paths in the chapters array are relative to book.yml.
+
+The chapters array supports four element types:
+
+**1. Cover** (object with 'cover' key):
+
+```yaml
+chapters:
+  - cover: cover.md          # Markdown file: landing page shown when the book is opened
+                              # Not shown in the TOC sidebar.
+```
+
+**2. Plain chapter** (string):
+
+```yaml
+chapters:
+  - 01-introduction.md
+```
+
+**3. Part** (object with 'part' and 'chapters' keys):
+
+```yaml
+chapters:
+  - part: part1.md
+    chapters:
+      - 01-introduction.md
+      - 02-getting-started.md
+```
+
+The part file's h1 becomes the part title, and the body text (if any)
+is shown as the part's opening page.
+
+**4. Appendix** (object with 'appendix' key, value is array of chapter files):
+
+```yaml
+chapters:
+  - appendix:
+    - a1-references.md
+    - a2-glossary.md
+```
+
+These can be combined freely:
+
+```yaml
+chapters:
+  - cover: cover.md
+  - part: part1.md
+    chapters:
+      - 01-introduction.md
+      - 02-getting-started.md
+  - part: part2.md
+    chapters:
+      - 03-advanced.md
+  - appendix:
+    - a1-references.md
+```
+
+Part numbering is sequential across parts (1, 2, 3, ...).
+Appendix numbering uses letters (A, B, C, ...).
+
+### Social metadata (Open Graph)
+
+Every build emits Open Graph tags in `<head>` so the generated `index.html`
+previews nicely when shared: `og:type` (`book`), `og:title` and `og:site_name`
+(the book title), `og:locale` (derived from `language`, e.g. `ja` → `ja_JP`),
+and `book:author` when `author` is set. If a description is available (the
+`description` field, or auto-extracted from the cover/first chapter) it is also
+emitted as `<meta name="description">` and `og:description`. A
+`twitter:card` (`summary`) tag is always included. No image tag is produced.
+
+When `site_url` is set, `og:url` and `<link rel="canonical">` are emitted with
+that URL verbatim (the book is a single page, so it has one canonical URL).
+Running `setup-github-review` seeds `site_url` in book.yml from `repository`
+(the GitHub Pages URL — `https://<owner>.github.io/<repo>/`, or
+`https://<owner>.github.io/` for an `<owner>.github.io` repo), so books deployed
+that way get `og:url` automatically; edit it for a custom domain.
+
+### Example book.yml (simple)
+
+```yaml
+title: "My Software Guide"
+author: "Author Name"
+language: "ja"
+chapters:
+  - 01-introduction.md
+  - 02-getting-started.md
+  - 03-advanced.md
+```
+
+### Example book.yml (with parts and appendix)
+
+```yaml
+title: "My Software Guide"
+author: "Author Name"
+language: "ja"
+chapters:
+  - part: part1.md
+    chapters:
+      - 01-introduction.md
+      - 02-getting-started.md
+  - part: part2.md
+    chapters:
+      - 03-advanced.md
+      - 04-deployment.md
+  - appendix:
+    - a1-config-reference.md
+```
+
+## Translations (Multi-Language)
+
+ligarb supports building the same book in multiple languages. A parent
+config file (hub) defines shared settings and points to per-language
+config files.
+
+### Hub config (book.yml)
+
+```yaml
+repository: "https://github.com/user/repo"
+ai_generated: true
+translations:
+  ja: book.ja.yml
+  en: book.en.yml
+```
+
+### Per-language config (book.ja.yml)
+
+```yaml
+title: "マニュアル"
+language: "ja"
+inherit: book.yml
+chapters:
+  - chapters/ja/01-intro.md
+```
+
+### Per-language config (book.en.yml)
+
+```yaml
+title: "Manual"
+language: "en"
+inherit: book.yml
+chapters:
+  - chapters/en/01-intro.md
+```
+
+### Building
+
+There are two ways to build a multi-language book:
+
+**Hub build** — pass the hub config to build all languages at once.
+Produces a single output with a language switcher linking all translations:
+
+```
+ligarb build book.yml        # Builds all languages, adds language switcher
+```
+
+**Standalone build** — pass a per-language config to build one language.
+No language switcher is generated. The `inherit` field loads the hub's
+inheritable settings (repository, style, ai_generated, etc.) as defaults:
+
+```
+ligarb build book.ja.yml     # Builds only Japanese, no language switcher
+```
+
+### Inheritance rules
+
+- The hub's settings (repository, style, ai_generated, etc.) are
+  inherited by each per-language config as defaults.
+- Per-language configs can override any inherited setting.
+- title, language, and chapters are always per-language (required in
+  each per-language config).
+- output_dir is NOT inherited — it always comes from the config file
+  passed directly to `ligarb build`.
+
+The hub config does not need 'title' or 'chapters' fields — it only
+needs 'translations'. If the hub has no 'chapters', it is treated
+purely as a translations hub.
+
+### Language switcher
+
+- Hub build produces a single index.html containing all languages.
+  A language switcher in the sidebar header (e.g. `[JA | EN]`) toggles
+  visibility via JavaScript.
+- The current language button is highlighted; others switch the display.
+
+## Directory Structure
+
+A typical book project has this structure:
+
+```
+my-book/
+├── book.yml              # Configuration file
+├── part1.md              # Part opening page (optional)
+├── 01-introduction.md    # Markdown source files
+├── 02-getting-started.md
+├── 03-advanced.md
+└── images/               # Image files (optional)
+    ├── screenshot.png
+    └── diagram.svg
+```
+
+After running `ligarb build`, the output is:
+
+```
+my-book/
+└── build/
+    ├── index.html        # Single-page HTML book
+    ├── js/               # Auto-downloaded (only if needed)
+    ├── css/              # Auto-downloaded (only if needed)
+    └── images/           # Copied image files
+```
+
+## Markdown Authoring
+
+### Basics
+
+Each Markdown file represents one chapter. ligarb uses GitHub Flavored
+Markdown (GFM) via kramdown. Supported syntax includes:
+
+- Headings (# h1, ## h2, ### h3) — used for TOC generation
+- Code blocks with language-specific syntax highlighting (\`\`\` fenced blocks)
+- Tables, task lists, strikethrough, and other GFM extensions
+- Inline HTML
+
+Each file must start with an h1 heading (`#`). This becomes the chapter
+title in the TOC. Use h2 (`##`) and h3 (`###`) for sections within the chapter.
+
+### Images
+
+Place image files in the `images/` directory next to book.yml.
+Reference them from Markdown with relative paths:
+
+```markdown
+![Screenshot](images/screenshot.png)
+```
+
+ligarb rewrites all local image paths to `images/{basename}` in the output
+(directory components are stripped). Images are copied from the `images/`
+directory next to book.yml — only top-level files, not subdirectories.
+
+This means:
+- `![img](images/foo.png)` and `![img](sub/dir/foo.png)` both become
+  `images/foo.png` in the output.
+- All image filenames must be unique regardless of source directory.
+- Remote URLs (http://, https://, data:) are left unchanged.
+- In multi-language builds, all languages share the same `images/` pool.
+
+### Footnotes
+
+Footnotes use kramdown syntax:
+
+```markdown
+This is a sentence with a footnote[^1].
+
+[^1]: This is the footnote content.
+```
+
+Footnote IDs are scoped per chapter to avoid collisions in the single-page
+output.
+
+### Admonitions
+
+GFM-style blockquote alerts are converted to styled admonition boxes.
+Five types are supported: NOTE, TIP, WARNING, CAUTION, IMPORTANT.
+
+Syntax:
+
+```markdown
+> [!NOTE]
+> This is a note.
+
+> [!TIP]
+> Helpful advice here.
+
+> [!WARNING]
+> Be careful about this.
+
+> [!CAUTION]
+> Dangerous operation.
+
+> [!IMPORTANT]
+> Critical information.
+```
+
+Each type renders with a distinct color and icon:
+
+| Type | Color | Icon |
+|------|-------|------|
+| NOTE | blue | info |
+| TIP | green | lightbulb |
+| WARNING | yellow | warning |
+| CAUTION | red | stop |
+| IMPORTANT | purple | exclamation |
+
+### Cross-References
+
+Link to other chapters or headings using standard Markdown relative links.
+ligarb resolves .md file references to internal anchors in the single-page
+output.
+
+Syntax:
+
+```markdown
+[link text](other-chapter.md)            Link to a chapter
+[link text](other-chapter.md#Heading)    Link to a specific heading
+[](other-chapter.md)                     Auto-fill with chapter title
+[](other-chapter.md#Heading)             Auto-fill with heading text
+```
+
+The .md path is resolved relative to the current Markdown file's directory.
+The heading fragment is matched against heading IDs (case-insensitive,
+normalized the same way heading slugs are generated).
+
+When the link text is empty, ligarb fills it with the target's display text:
+- Chapter link: the chapter's display title (e.g. "3. Config Guide")
+- Heading link: the heading's display text (e.g. "3.2 Setup")
+
+If a referenced chapter or heading does not exist, the build fails with an
+error message indicating the broken reference and its source file.
+
+External URLs ending in .md (e.g. https://example.com/README.md) are not
+affected — only relative paths are resolved.
+
+### Index
+
+Mark terms for the book index using Markdown link syntax with `#index`:
+
+```markdown
+[Ruby](#index)                           Index the link text as-is
+[dynamic typing](#index:動的型付け)       Index under a specific term
+[Ruby](#index:Ruby,Languages/Ruby)       Multiple index entries (comma-separated)
+[Ruby](#index:Languages/Ruby)            Hierarchical: Languages > Ruby
+```
+
+The link is rendered as plain text in the output (no link styling).
+An "Index" section is automatically appended at the end of the book,
+with terms sorted alphabetically and grouped by first character.
+
+Clicking an index entry navigates to the exact location in the chapter.
+
+### Bibliography
+
+Cite references in the text using Markdown link syntax with `#cite`:
+
+```markdown
+[Ruby](#cite:matz1995)       Cite by key; rendered as Ruby[Matsumoto, 1995]
+```
+
+Define a bibliography data file in book.yml:
+
+```yaml
+bibliography: references.yml   # YAML format
+bibliography: references.bib   # BibTeX format
+```
+
+The format is auto-detected by file extension (.bib = BibTeX, otherwise YAML).
+
+**YAML format** — maps keys to reference data:
+
+```yaml
+matz1995:
+  author: "Yukihiro Matsumoto"
+  title: "The Ruby Programming Language"
+  year: 1995
+  url: "https://www.ruby-lang.org"
+  publisher: "O'Reilly"
+  doi: "10.1234/example"
+```
+
+**BibTeX format:**
+
+```bibtex
+@book{matz1995,
+  author = {Yukihiro Matsumoto},
+  title = {The Ruby Programming Language},
+  year = {1995},
+  publisher = {O'Reilly},
+  url = {https://www.ruby-lang.org}
+}
+```
+
+BibTeX notes:
+- Entry types (@book, @article, etc.) are preserved for formatting
+- Field values can use {braces} or "quotes"
+- Nested braces are supported one level deep (`{The {Ruby} Language}`)
+- Lines starting with `%` are comments
+
+Supported fields (YAML and BibTeX):
+author, title, year, url, publisher, journal, booktitle, volume,
+number, pages, edition, doi, editor, note.
+
+Formatting by type:
+
+| Type | Format |
+|------|--------|
+| book | Author. *Title*. Edition. Publisher, Year. |
+| article | Author. "Title". Journal, Volume(Number), Pages, Year. |
+| inproceedings | Author. "Title". In Booktitle, Pages, Year. |
+| other/YAML | Author. Title. Publisher/Journal, Volume, Pages, Year. |
+
+If url is present, the title becomes a link. If doi is present, a DOI link
+is appended.
+
+The citation is rendered as a superscript [author, year] link that navigates
+to the "Bibliography" section at the end of the book. Hovering the link shows
+the full reference. The bibliography section lists all cited entries sorted by
+author and year.
+
+A warning is printed and the citation is rendered as [key?] (highlighted in
+red) if a cite key is not found in the bibliography file.
+If no bibliography file is configured, `#cite:` links are converted to
+plain text spans (the link text is preserved but no citation label is added).
+
+## Fenced Code Blocks
+
+The following fenced code block types are automatically detected and
+rendered. Required JS/CSS is auto-downloaded on first build to build/js/
+and build/css/.
+
+| Block type | Description |
+|-----------|-------------|
+| `` ```ruby ``, `` ```python ``, etc. | Syntax highlighting (highlight.js, BSD-3-Clause) |
+| `` ```mermaid `` | Diagrams: flowcharts, sequence, bar/line/pie charts, gantt, mindmap, etc. (mermaid, MIT) |
+| `` ```math `` | LaTeX math equations (KaTeX, MIT) |
+| `` ```functionplot `` | Function graphs (function-plot + d3, MIT) |
+
+These are rendered visually in the output HTML — use them freely.
+
+### Mermaid syntax checking
+
+When a build contains `` ```mermaid `` blocks and Node.js is available, ligarb
+validates each diagram with the bundled mermaid parser at build time. Diagrams
+that fail to parse are reported as warnings with their `file:line` location, for
+example:
+
+```
+Warning: mermaid syntax error in chapters/05-diagrams.md:42
+  Parse error on line 2:
+  ...
+```
+
+The build still succeeds (the broken diagram renders an error box in the output
+instead of an SVG). The check is skipped silently when Node.js is not installed.
+HTML inside node labels (such as `<br>`) is exempt from the check and never warns.
+
+### Mermaid examples
+
+Flowchart:
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B{Check}
+    B -->|Yes| C[OK]
+    B -->|No| D[Retry]
+```
+````
+
+Sequence diagram:
+
+````markdown
+```mermaid
+sequenceDiagram
+    Client->>Server: Request
+    Server-->>Client: Response
+```
+````
+
+Bar chart:
+
+````markdown
+```mermaid
+xychart
+    title "Monthly Sales"
+    x-axis ["Jan", "Feb", "Mar", "Apr", "May"]
+    y-axis "Revenue" 0 --> 500
+    bar [120, 230, 180, 350, 410]
+    line [120, 230, 180, 350, 410]
+```
+````
+
+Line chart (line only):
+
+````markdown
+```mermaid
+xychart
+    title "Temperature"
+    x-axis ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
+    y-axis "°C" -5 --> 30
+    line [2, 4, 10, 16, 22, 26]
+```
+````
+
+Pie chart:
+
+````markdown
+```mermaid
+pie title Browser Share
+    "Chrome" : 65
+    "Safari" : 19
+    "Firefox" : 4
+    "Other" : 12
+```
+````
+
+Gantt chart:
+
+````markdown
+```mermaid
+gantt
+    title Project Plan
+    dateFormat YYYY-MM-DD
+    section Design
+        Requirements :a1, 2025-01-01, 14d
+        Architecture :a2, after a1, 10d
+    section Dev
+        Implementation :b1, after a2, 21d
+        Testing        :b2, after b1, 14d
+```
+````
+
+Mindmap:
+
+````markdown
+```mermaid
+mindmap
+    root((Project))
+        Frontend
+            React
+            CSS
+        Backend
+            API
+            Database
+```
+````
+
+### Math (KaTeX, LaTeX syntax)
+
+````markdown
+```math
+E = mc^2
+```
+````
+
+Inline math uses `$...$` syntax within text:
+
+```
+The equation $E = mc^2$ is well-known.
+```
+
+Rules for inline math:
+- `$$` is not matched (use `` ```math `` for display math)
+- `$` followed by a space is not matched (e.g. $10)
+- `$` preceded by a space is not matched
+- Content inside `<code>` and `<pre>` is not affected
+- The content is rendered with KaTeX (displayMode: false)
+
+### Function plot
+
+````markdown
+```functionplot
+y = sin(x)
+y = x^2 - 1
+range: [-2pi, 2pi]
+yrange: [-3, 3]
+```
+````
+
+Function plot syntax:
+- `y = <expr>` — Standard function (e.g. `y = sin(x)`)
+- `r = <expr>` — Polar function (e.g. `r = cos(2*theta)`)
+- `parametric: <x>, <y>` — Parametric curve (e.g. `parametric: cos(t), sin(t)`)
+- Bare expression — Treated as `y = <expr>`
+
+Options (one per line):
+- `range` / `xrange: [min, max]` — X-axis range (supports pi, e.g. `[-2pi, 2pi]`)
+- `yrange: [min, max]` — Y-axis range
+- `width: <pixels>` — Plot width (default: 600)
+- `height: <pixels>` — Plot height (default: 400)
+- `title: <text>` — Plot title
+- `grid: true` — Show grid lines
+
+## Output Customization
+
+### Custom CSS
+
+Add a `style` field to book.yml to inject custom CSS:
+
+```yaml
+style: "custom.css"
+```
+
+The custom CSS file is read and embedded as-is into a `<style>` tag in the
+generated HTML, after the default styles. No sanitization or escaping is
+applied — this is safe under the trusted authoring model, but means the CSS
+file should be treated as part of the trusted source. You can override any
+CSS custom property (e.g. colors, fonts, sidebar width) or add new rules.
+
+Example custom.css:
+
+```css
+:root {
+  --color-accent: #e63946;
+  --sidebar-width: 320px;
+}
+```
+
+### Dark Mode
+
+The generated HTML includes a dark mode toggle button (moon icon) in the
+sidebar header. The user's preference is saved to localStorage and persists
+across page reloads.
+
+Custom CSS can override dark mode colors using the `[data-theme="dark"]`
+selector.
+
+### Edit on GitHub
+
+Add a `repository` field to book.yml:
+
+```yaml
+repository: "https://github.com/user/repo"
+```
+
+Each chapter will show a "View on GitHub" link pointing to:
+`{repository}/blob/HEAD/{path-from-git-root}`
+
+The chapter path is resolved relative to the Git repository root.
+
+### Previous/Next Navigation
+
+Each chapter displays Previous and Next navigation links at the bottom.
+These follow the flat chapter order (including across parts and appendix).
+Cover pages do not show navigation.
+
+## Write Command
+
+The `write` command generates a complete book using AI (Claude CLI).
+
+### brief.yml fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `title` | required | — | The book title. |
+| `language` | optional | `"ja"` | Language. |
+| `audience` | optional | — | Target audience (used in the prompt). |
+| `notes` | optional | — | Additional instructions for Claude (free text). |
+| `sources` | optional | — | Reference files for AI context. Array of strings or `{path:, label:}` objects. Paths relative to brief.yml. |
+| `author` | optional | — | Passed through to book.yml. |
+| `output_dir` | optional | — | Passed through to book.yml. |
+| `chapter_numbers` | optional | — | Passed through to book.yml. |
+| `style` | optional | — | Passed through to book.yml. |
+| `repository` | optional | — | Passed through to book.yml. |
+
+The book is generated in the directory containing brief.yml.
+Example: `ligarb write ruby_book/brief.yml` creates files in ruby_book/.

data/lib/ligarb/builder.rb

@@ -41,13 +41,18 @@ module Ligarb
 
       bibliography = resolve_citations!(all_chapters)
 
+      FileUtils.mkdir_p(@config.output_path)
+
+      md_name = "index.md"
+      write_markdown_bundle(all_chapters, File.join(@config.output_path, md_name))
+
       html = Template.new.render(config: @config, chapters: all_chapters,
                                  structure: structure, assets: assets,
                                  index_entries: index_entries,
                                  bibliography: bibliography,
-                                 github_review: github_review_data(@config))
+                                 github_review: github_review_data(@config),
+                                 ai_md: md_name)
 
-      FileUtils.mkdir_p(@config.output_path)
       output_file = File.join(@config.output_path, "index.html")
       File.write(output_file, html)
 
@@ -76,6 +81,14 @@ module Ligarb
         all_lang_chapters.concat(lang_data[:chapters])
       end
 
+      FileUtils.mkdir_p(output_path)
+
+      langs.each do |ld|
+        md_name = "index.#{ld[:lang]}.md"
+        write_markdown_bundle(ld[:chapters], File.join(output_path, md_name))
+        ld[:ai_md] = md_name
+      end
+
       assets = AssetManager.new(output_path)
       assets.detect(all_lang_chapters)
       assets.provision!
@@ -428,6 +441,14 @@ module Ligarb
       text.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
     end
 
+    # Emit a clean Markdown full-text version of the book alongside index.html.
+    # AI/LLM readers (and the in-page hint) point here for low-noise content.
+    # The bundle is the concatenated chapter sources in flat reading order.
+    def write_markdown_bundle(chapters, path)
+      body = chapters.map { |ch| ch.source.strip }.reject(&:empty?).join("\n\n")
+      File.write(path, body.empty? ? body : "#{body}\n")
+    end
+
     def copy_images
       images_dir = File.join(@config.base_dir, "images")
       return unless Dir.exist?(images_dir)

data/lib/ligarb/chapter.rb

@@ -8,7 +8,7 @@ module Ligarb
     class CrossReferenceError < StandardError; end
 
     attr_reader :title, :slug, :html, :headings, :number, :appendix_letter, :index_entries, :cite_entries,
-                :path, :mermaid_blocks
+                :path, :mermaid_blocks, :source
     attr_accessor :part_title, :cover, :relative_path
 
     Heading = Struct.new(:level, :text, :id, :display_text, keyword_init: true)

data/lib/ligarb/config.rb

@@ -233,6 +233,9 @@ module Ligarb
 
     def load_translations_hub(data)
       @title = data.fetch("title", "")
+      # The hub writes its combined build here; serve needs output_path to work
+      # even though hub init returns before the normal output_dir assignment.
+      @output_dir = data.fetch("output_dir", "build")
       @translations = []
 
       trans = data["translations"]

data/lib/ligarb/mermaid_checker.rb

@@ -39,7 +39,10 @@ module Ligarb
       error_count = 0
       results.each do |result|
         error = result["error"]
-        next unless error
+        # "environment" errors are limitations of the Node DOM stub (e.g. a node
+        # label containing HTML like <br>), not diagram syntax errors, so they
+        # would be false positives — skip them. See assets/mermaid_check.mjs.
+        next unless error && result["kind"] == "syntax"
 
         error_count += 1
         block = blocks[result["id"]]

data/lib/ligarb/template.rb

@@ -13,7 +13,7 @@ module Ligarb
       @css_path      = File.join(ASSETS_DIR, "style.css")
     end
 
-    def render(config:, chapters:, structure:, assets:, index_entries: [], bibliography: [], github_review: nil)
+    def render(config:, chapters:, structure:, assets:, index_entries: [], bibliography: [], github_review: nil, ai_md: nil)
       css = File.read(@css_path)
       template = File.read(@template_path)
 
@@ -42,6 +42,7 @@ module Ligarb
       b.local_variable_set(:og_description, og_description(config, chapters))
       b.local_variable_set(:og_locale, og_locale(config.language))
       b.local_variable_set(:og_url, og_url(config))
+      b.local_variable_set(:ai_md, ai_md)
 
       ERB.new(template, trim_mode: "-").result(b)
     end
@@ -74,6 +75,7 @@ module Ligarb
           footer: cfg.effective_footer,
           index_tree: build_index_tree(ld[:index_entries], ld[:chapters]),
           bibliography: ld[:bibliography],
+          ai_md: ld[:ai_md],
         }
       end
 
@@ -99,6 +101,7 @@ module Ligarb
       b.local_variable_set(:og_description, og_description(first_config, first[:chapters]))
       b.local_variable_set(:og_locale, og_locale(first_config.language))
       b.local_variable_set(:og_url, og_url(first_config))
+      b.local_variable_set(:ai_md, nil)
 
       ERB.new(template, trim_mode: "-").result(b)
     end

data/lib/ligarb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ligarb
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/templates/book.html.erb

@@ -17,6 +17,15 @@
 <meta property="og:description" content="<%= h(og_description) %>">
 <%- end -%>
 <meta name="twitter:card" content="summary">
+<%- if multilang -%>
+<%- langs.each do |ld| -%>
+<%- if ld[:ai_md] -%>
+<link rel="alternate" type="text/markdown" hreflang="<%= h(ld[:language]) %>" href="<%= h(ld[:ai_md]) %>" title="<%= h(ld[:title]) %> (Markdown)">
+<%- end -%>
+<%- end -%>
+<%- elsif ai_md -%>
+<link rel="alternate" type="text/markdown" href="<%= h(ai_md) %>" title="Markdown version">
+<%- end -%>
 <%- if author && !author.to_s.empty? -%>
 <meta property="book:author" content="<%= h(author) %>">
 <%- end -%>
@@ -272,6 +281,15 @@
 <button class="sidebar-toggle" id="sidebar-toggle" aria-label="Toggle sidebar">&#9776;</button>
 
 <main class="content" id="content">
+<%- if multilang -%>
+  <%- langs.each do |ld| -%>
+  <%- if ld[:ai_md] -%>
+  <p class="ai-md-hint lang-content" data-lang="<%= ld[:lang] %>">For AI/LLM readers: a clean Markdown full-text version of this book is at <a href="<%= h(ld[:ai_md]) %>"><%= h(ld[:ai_md]) %></a>.</p>
+  <%- end -%>
+  <%- end -%>
+<%- elsif ai_md -%>
+  <p class="ai-md-hint">For AI/LLM readers: a clean Markdown full-text version of this book is at <a href="<%= h(ai_md) %>"><%= h(ai_md) %></a>.</p>
+<%- end -%>
 <%- if multilang -%>
   <%- langs.each do |ld| -%>
   <%- ld[:chapters].select(&:cover?).each do |chapter| -%>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ligarb
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - ligarb contributors
@@ -65,6 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +121,7 @@ files:
 - assets/review.js
 - assets/serve.js
 - assets/style.css
+- docs/help.md
 - exe/ligarb
 - lib/ligarb/asset_manager.rb
 - lib/ligarb/builder.rb