Make the book engaging: narrative voice + Mermaid diagrams + illustrations

- Rewrite part1/history.md as a story ("the 60-year quest to make machines
  remember"), six acts with scene-setting, protagonists, tension and resolution;
  drop-cap lead, 🧬 "DNA passed to OKF" callouts per era.
- Mermaid diagrams (vendored mermaid.min.js + <pre class="mermaid"> via mermaid-init.js,
  no preprocessor): an evolution timeline, word2vec analogy, RAG flow, and a
  "six rivers into OKF" convergence; plus RAG-flow and knowledge-graph diagrams in
  foundations.md. Air-gap (vendored), render on web and in the PDF.
- print-pdf.js waits for window.__okfMermaidDone so diagrams render in the PDF.
- Figure/diagram/era-banner CSS. English mirror re-translated (diagram labels localized).

Verified: links + fences OK in both books.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: supachai-j

book-en/book.toml

@@ -11,7 +11,7 @@ preferred-dark-theme = "navy"
 git-repository-url = "https://github.com/supachai-j/open-knowledge-format-starter"
 edit-url-template = "https://github.com/supachai-j/open-knowledge-format-starter/edit/main/book-en/{path}"
 additional-css = ["css/custom.css"]
-additional-js = ["js/lang-switch.js"]
+additional-js = ["js/mermaid.min.js", "js/mermaid-init.js", "js/lang-switch.js"]
 no-section-label = false
 
 [output.html.search]

book-en/css/custom.css

@@ -95,6 +95,22 @@
 }
 .okf-embed-fallback .okf-url { font-family: ui-monospace, monospace; word-break: break-all; }
 
+/* ── Figures, diagrams, illustrations ─────────────────────────── */
+pre.mermaid { background: transparent; border: 0; text-align: center; margin: 1.3rem 0; line-height: normal; }
+pre.mermaid svg { max-width: 100%; height: auto; }
+figure.okf-fig { margin: 1.4rem 0; text-align: center; }
+figure.okf-fig svg { max-width: 100%; height: auto; }
+figure.okf-fig figcaption { font-size: 0.85rem; color: var(--sidebar-fg, #6b7280); margin-top: 0.5rem; font-style: italic; }
+.okf-era {
+  margin: 1.8rem 0 0.6rem; padding: 0.55rem 0.95rem; border-radius: 10px;
+  background: linear-gradient(90deg, rgba(139,92,246,0.13), transparent);
+  border-left: 4px solid #8b5cf6;
+}
+.okf-era .yr { font-weight: 800; color: #8b5cf6; font-size: 0.8rem; letter-spacing: 0.03em; }
+.okf-era .ti { font-weight: 700; font-size: 1.15rem; display: block; margin-top: 0.1rem; }
+.okf-lead { font-size: 1.05rem; line-height: 1.85; }
+.okf-lead .drop { float: left; font-size: 3rem; line-height: 0.8; font-weight: 800; color: #8b5cf6; padding: 0.3rem 0.5rem 0 0; }
+
 /* ── Full-page A4 cover in the PDF ─────────────────────────────── */
 @media print {
   @page { size: A4; margin: 17mm 15mm; }   /* room for the running header + page-number footer */

book-en/js/mermaid-init.js

@@ -0,0 +1,22 @@
+// Render Mermaid diagrams written as <pre class="mermaid">…</pre> (no preprocessor needed).
+// Sets window.__okfMermaidDone so the PDF renderer can wait for diagrams to finish.
+(function () {
+  window.__okfMermaidDone = false;
+  async function run() {
+    if (!window.mermaid) { window.__okfMermaidDone = true; return; }
+    try {
+      window.mermaid.initialize({
+        startOnLoad: false,
+        theme: 'neutral',
+        securityLevel: 'loose',
+        fontFamily: "'Noto Sans Thai','Loma',sans-serif",
+        flowchart: { htmlLabels: true, curve: 'basis', useMaxWidth: true },
+        themeVariables: { primaryColor: '#ede9fe', primaryBorderColor: '#8b5cf6', lineColor: '#8b5cf6' },
+      });
+      await window.mermaid.run({ querySelector: 'pre.mermaid' });
+    } catch (e) { console.error('mermaid', e); }
+    window.__okfMermaidDone = true;
+  }
+  if (document.readyState !== 'loading') run();
+  else document.addEventListener('DOMContentLoaded', run);
+})();

book-en/js/mermaid.min.js

@@ -24,7 +24,7 @@ FRAME: Bacteroides
 
 **Example** (RDF triple): `TimBernersLee — invented — WorldWideWeb` (subject–predicate–object)
 
-**In OKF:** Markdown links between concepts serve a similar role to triples but are **untyped** — the type of relationship lives in prose (much lighter than OWL).
+**In OKF:** Markdown links between concepts serve a similar role to triples but are **untyped** — the type of relationship lives in the prose (much lighter than OWL).
 
 ## 3. Inverted Index
 
@@ -33,8 +33,8 @@ FRAME: Bacteroides
 **Example:**
 | Term | Documents |
 |------|-----------|
-| cat | D1, D2 |
-| dog | D3 |
+| cat  | D1, D2 |
+| dog  | D3 |
 
 Search "dog" → returns D3 immediately, without scanning every document.
 
@@ -69,7 +69,14 @@ Search "dog" → returns D3 immediately, without scanning every document.
 
 **What it is:** Retrieving relevant information and inserting it into the LLM's context at query time to ground the answer (reduce hallucination, enable citation).
 
-**Example** (5 steps): `chunk → embed → store → retrieve top-k → generate`
+**Example** (5 steps):
+
+<pre class="mermaid">
+flowchart LR
+  D["Documents"] --> C["chunk"] --> E["embed"] --> S["vector store"]
+  Q["Query"] --> R["retrieve top-k"]
+  S --> R --> G["LLM generate<br/>grounded answer"]
+</pre>
 
 **In OKF:** The wiki = Layer 1 (pre-synthesized; finding it in the wiki is sufficient); RAG = Layer 2 (mining raw documents when the wiki does not yet cover the topic).
 
@@ -85,7 +92,14 @@ Search "dog" → returns D3 immediately, without scanning every document.
 
 **What it is:** A graph of entities (nodes) + typed relationships (edges) — "things, not strings" — enabling entity-level disambiguation and reasoning.
 
-**Example:** `[Customer A] —ordered→ [Order 123] —contains→ [Product X]`
+**Example:**
+
+<pre class="mermaid">
+flowchart LR
+  CU["Customer A"] -->|orders| O["Order 123"]
+  O -->|contains| P["Product X"]
+  CU -->|in segment| SEG["High-value"]
+</pre>
 
 **In OKF:** The entire bundle forms a knowledge graph (concepts = nodes, links = edges) — viewable with `okf-viz.py`.