Maamar Book Pipeline

A reusable pipeline for packaging Chassidic maamar translation artifacts into a Paged.js book template, with:

• staged JSON artifact generation and preservation;
• a normalized Margin Folio data/maamar.json render object;
• browser web preview through Paged.js;
• deterministic PDF rendering with Puppeteer;
• an online manual page-break editor for cases where automatic reflow is not ideal.

The repository includes a working sample from ד״ה השם נפשנו בחיים so the preview can run immediately.

Quick start

npm install
npm run preview
# open http://localhost:5173

Render a PDF:

npm run render:pdf

The PDF is written to dist/maamar-book.pdf.

Online preview + manual breaks

The web preview has an Edit breaks mode. In that mode each chapter, segment, synthesis block, and phrase row gets an Insert page break toggle.

Workflow:

1. Open the online preview.
2. Enable Edit breaks.
3. Toggle breaks before blocks that reflow poorly.
4. The browser stores breaks in localStorage and immediately rerenders.
5. Click Export breaks to download manual-breaks.json.
6. Commit that file as data/manual-breaks.json so the same breaks are used by the PDF renderer and by GitHub Pages.

Manual break keys are stable, for example:

{"breaks":["segment:22", "row:22:4", "synthesis:8"]}

Build staged artifacts from a maamar project

python3 scripts/assemble_artifacts.py   --project /path/to/maamar_project   --out .

The script copies/preserves staged artifacts and updates:

• artifacts/stage_c_translation/translations.json
• artifacts/stage_c_translation/translations_by_segment/
• artifacts/stage_c_translation/hybrid_interpretive_translation/
• artifacts/stage_d_bridges/bridges_summaries.json
• artifacts/render/margin_folio_maamar.json
• data/maamar.json
• data/sefaria-cache.json when available

If the project already has artifacts/render/margin_folio_maamar.json, that is used as the canonical render object. Otherwise the script attempts a conservative assembly from translations + bridge metadata.

Repository layout

• css/, js/, index.html — Paged.js Margin Folio template and online preview.
• js/manual-breaks.js — online manual page-break editor.
• data/maamar.json — normalized render JSON consumed by the template.
• data/manual-breaks.json — reproducible manual page-break decisions.
• scripts/assemble_artifacts.py — staged artifact packager / render JSON assembler.
• scripts/render-pdf.mjs — deterministic local/CI PDF renderer.
• skills/maamar-book-pipeline/SKILL.md — Hermes skill for this workflow.
• examples/ — sample generated artifacts.

GitHub Pages

This repo ships a GitHub Pages workflow. Pushing to main publishes the web preview. For public repos, the preview URL is normally:

https://litescale-ai.github.io/maamar-book-pipeline/

Final-output discipline

This package is for deterministic packaging/rendering. Upstream extraction, translation, hybrid authoring, and Claude language polishing should remain recorded in the staged artifacts and model manifests. Do not replace LLM-authored hybrid rows with deterministic fallback text.