From c765fe91836108a4ec6123c5b7dca3f9266ab257 Mon Sep 17 00:00:00 2001 From: ZDDC Date: Thu, 4 Jun 2026 14:07:36 -0500 Subject: [PATCH] feat(pandoc): named doctype templates + front-matter numbering toggle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the single always-numbered viewer-template.html with a templates/ directory of named doctype templates that share partials: - templates/_head.html — + all CSS (numbering CSS now scoped behind a body.numbered class instead of being applied unconditionally) - templates/_doc.html — shared TOC-sidebar body (report/specification) - templates/_scripts.html — shared JS - templates/{report,specification}.html — TOC-layout doctypes - templates/letter.html — single-column letterhead, no TOC A document selects its template with `template: ` in YAML front matter (default report) and turns on legal numbering with `numbering: true` (default off). Pandoc passes both fields straight from the front matter — the numbering toggle needs no converter code. Retire custom.css (folded into _head.html, gated) and the old viewer-template.html. CLI: convert md→html resolves templates/.html (name from front matter, sanitized, default report); convert-diff uses templates/report.html and no longer passes --css=custom.css. README updated. Server (zddc/internal/convert) still uses its own embedded copy and is unchanged here; it migrates to this templates/ dir in the next commit. Co-Authored-By: Claude Opus 4.8 (1M context) --- pandoc/README.md | 24 +- pandoc/convert | 48 +- pandoc/convert-diff | 55 +- pandoc/custom.css | 163 ---- pandoc/templates/_doc.html | 112 +++ pandoc/templates/_head.html | 778 +++++++++++++++++ pandoc/templates/_scripts.html | 259 ++++++ pandoc/templates/letter.html | 56 ++ pandoc/templates/report.html | 9 + pandoc/templates/specification.html | 9 + pandoc/viewer-template.html | 1261 --------------------------- 11 files changed, 1282 insertions(+), 1492 deletions(-) delete mode 100644 pandoc/custom.css create mode 100644 pandoc/templates/_doc.html create mode 100644 pandoc/templates/_head.html create mode 100644 pandoc/templates/_scripts.html create mode 100644 pandoc/templates/letter.html create mode 100644 pandoc/templates/report.html create mode 100644 pandoc/templates/specification.html delete mode 100644 pandoc/viewer-template.html diff --git a/pandoc/README.md b/pandoc/README.md index 4140aec..afe7207 100644 --- a/pandoc/README.md +++ b/pandoc/README.md @@ -7,8 +7,8 @@ A collection of tools for converting Markdown documents to HTML with a professio > The shell scripts in this folder are standalone CLI/batch tools. `zddc-server` > implements its **own** on-demand conversion (Go package `zddc/internal/convert`) > and does **not** call these scripts. It does, however, reuse the same -> `viewer-template.html` and `custom.css` (embedded at build time). See -> AGENTS.md → "Server-side document conversion" for the authoritative reference. +> `templates/` (embedded at build time). See AGENTS.md → "Server-side document +> conversion" for the authoritative reference. zddc-server can render any served `.md` on demand: requesting the sibling URL `/foo.docx` (or `.html` / `.pdf`) returns the converted bytes — no query @@ -25,10 +25,10 @@ that run the real binary inside a per-conversion bubblewrap sandbox memory/PID caps. I/O is via stdin/stdout plus a per-call scratch dir. There is no container runtime and no image pulling at request time. -The PDF flow is two-stage: pandoc renders the markdown through -`viewer-template.html` to standalone HTML, then headless Chromium prints that HTML -to PDF — preserving the viewer template's print-media CSS rather than going -through pandoc's LaTeX template. +The PDF flow is two-stage: pandoc renders the markdown through the selected +`templates/.html` to standalone HTML, then headless Chromium prints that +HTML to PDF — preserving the template's print-media CSS rather than going through +pandoc's LaTeX template. Converted bytes are cached at `/.zddc.d/converted/.` with mtime synced to the source, so a fresh cache hit is a stat-and-serve with no `exec`. @@ -61,7 +61,15 @@ working. Running against raw pandoc/chromium with no wrapper gives a working but - **Template integration**: Automatically applies the viewer template - **Progress tracking**: Real-time conversion status and summary -### Professional Viewer Template (`viewer-template.html`) +### Professional templates (`templates/`) + +Named doctype templates — `report.html`, `letter.html`, `specification.html` — +share `_head.html` / `_doc.html` / `_scripts.html` partials. A document selects one +with a `template:` field in its YAML front matter (default `report`), and turns on +legal-style heading numbering with `numbering: true` (default off). Both fields are +read by pandoc straight from the front matter. Server deployments additionally +resolve per-project/per-party overrides from `.zddc.d/templates/.html`. + - **Modern responsive design**: Works on desktop, tablet, and mobile - **Table of Contents (TOC)**: Auto-generated sidebar navigation with smooth scrolling - **Print optimization**: Professional formatting for PDF generation @@ -153,7 +161,7 @@ your-project/ ## Troubleshooting ### Common Issues -1. **Template not found**: Keep `viewer-template.html` beside the script (or input), or pass `-T /path/to/template.html` +1. **Template not found**: Keep the `templates/` directory beside the script (or input), or pass `-T /path/to/template.html` 2. **Permission errors**: Make sure `convert` script is executable (`chmod +x convert`) 3. **Missing output**: Check that output directory exists or use `-o` to create it 4. **Print issues**: Use "Print to PDF" in browser for best results diff --git a/pandoc/convert b/pandoc/convert index be4e75e..de8591e 100644 --- a/pandoc/convert +++ b/pandoc/convert @@ -8,7 +8,8 @@ show_help() { echo " -f: Force overwrite existing output files" echo " -o: Output directory (default: same as input)" echo " -t: Target format (md, html, docx) - overrides auto-detection" - echo " -T: Template file path (default: viewer-template.html)" + echo " -T: Template file path (default: templates/