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/