VARASYS/ZDDC
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(server): multi-template MD→HTML with .zddc.d/templates cascade

Browse source 
The convert engine renders markdown→HTML/PDF through named doctype templates
selected by the document's `template:` front matter, with per-project/per-party
overrides.

convert package:
- embed.go now embeds the whole templates/ dir (all: prefix so _-prefixed
  partials are included) as an embed.FS; drop the single viewer-template.html +
  custom.css embeds. New TemplateSet type + DefaultTemplateSet(name) returning the
  chosen doctype + its partials.
- ToHTML/ToPDF take a TemplateSet; writeTemplateSetToScratch materialises the
  template + partials flat into the per-call scratch dir (pandoc resolves
  $partial()$ from the template's own directory).

handler:
- converttemplate.go: templateNameFromFrontMatter (YAML front-matter scan,
  sanitized to a bare basename) + resolveTemplateSet, which overlays
  <level>/.zddc.d/templates/<name>.html overrides onto the embedded defaults,
  walking docDir→fsRoot so a party dir beats the project-global dir. An override
  may replace a doctype, a partial, or add a brand-new doctype.
- buildAndStore threads fsRoot + source into the html/pdf paths.

build: pandoc/templates/ is the single source of truth; shared/build-lib.sh
sync_pandoc_templates mirrors it into the embed dir on every build (cmp-guarded,
stale-pruning). convert.TestEmbeddedTemplatesMatchSource fails on drift.

Tests: drift + DefaultTemplateSet (convert); front-matter parse + cascade
override precedence (handler). Full ./... suite green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
ZDDC 2026-06-04 14:18:40 -05:00
parent c765fe9183
commit 1d816ae43a
18 changed files with 1714 additions and 1483 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
build
View file

@ -218,6 +218,12 @@ fi
cp "$SCRIPT_DIR/tables/dist/tables.html" "$SCRIPT_DIR/zddc/internal/handler/tables.html"
echo "Populated zddc/internal/handler/tables.html for //go:embed"
# Mirror the canonical conversion templates (pandoc/templates/) into the convert
# package's embed dir so //go:embed picks up the current bytes. pandoc/templates/
# is the single source of truth; the embed copy is a build artifact guarded by
# convert.TestEmbeddedTemplatesMatchSource. Runs on every build (incl. plain dev).
sync_pandoc_templates "$SCRIPT_DIR/pandoc/templates" "$SCRIPT_DIR/zddc/internal/convert/templates"
if [ "$RELEASE_CHANNEL" = "beta" ] || [ "$RELEASE_CHANNEL" = "stable" ]; then
# Assemble the embedded versions manifest from the per-tool .label sidecars

32
shared/build-lib.sh
View file

@ -83,6 +83,38 @@ concat_files() {
done
}
# Mirror the conversion templates from a canonical source dir into a build embed
# dir — go:embed can't follow symlinks, so the bytes must be a real copy under the
# Go package. Copies every *.html, drops stale destination *.html the source no
# longer has, and verifies byte-identity. Guarded at test time by
# convert.TestEmbeddedTemplatesMatchSource. Usage: sync_pandoc_templates <src> <dst>
sync_pandoc_templates() {
_src="$1"
_dst="$2"
if [ ! -d "$_src" ]; then
echo "error: missing template source dir: $_src" >&2
exit 1
fi
mkdir -p "$_dst"
# Drop destination templates the source no longer provides.
for _f in "$_dst"/*.html; do
[ -e "$_f" ] || continue
if [ ! -f "$_src/$(basename "$_f")" ]; then
rm -f "$_f"
fi
done
# Copy + verify each source template.
for _f in "$_src"/*.html; do
[ -e "$_f" ] || continue
cp "$_f" "$_dst/$(basename "$_f")"
if ! cmp -s "$_f" "$_dst/$(basename "$_f")"; then
echo "error: template sync mismatch: $_f" >&2
exit 1
fi
done
echo "Synced templates: $_src -> $_dst"
}
# ISO UTC build timestamp — set once when this file is sourced
build_timestamp=$(date -u +"%Y-%m-%d %H:%M:%S")

66
zddc/internal/convert/convert.go
View file

@ -14,8 +14,8 @@
// Public surface:
//
// ToDocx(ctx, source, meta) → []byte (DOCX bytes)
// ToHTML(ctx, source, meta) → []byte (standalone HTML)
// ToPDF (ctx, source, meta) → []byte (PDF, via HTML + chromium)
// ToHTML(ctx, source, meta, ts) → []byte (standalone HTML)
// ToPDF (ctx, source, meta, ts) → []byte (PDF, via HTML + chromium)
//
// Probe(ctx) → Capabilities (call once at startup)
// Available() → (Capabilities, bool)
@ -25,7 +25,7 @@
// All three converters are safe for concurrent use; each call gets a
// fresh scratch dir + (image-provided) sandbox.
//
// Metadata maps to the placeholders consumed by viewer-template.html.
// Metadata maps to the placeholders consumed by the doctype templates.
// title/tracking_number/revision/status/is_draft typically come from
// the source filename (zddc.ParseFilename); client/project/contractor/
// project_number from the .zddc cascade `convert:` block.
@ -42,8 +42,8 @@ import (
)
// Metadata is the variable bag passed to pandoc as `--variable k=v`
// pairs. Fields with zero values are omitted. The viewer-template.html
// uses `$if(field)$ … $endif$` blocks so absent fields render cleanly.
// pairs. Fields with zero values are omitted. The templates use
// `$if(field)$ … $endif$` blocks so absent fields render cleanly.
type Metadata struct {
Title string
TrackingNumber string
@ -58,6 +58,28 @@ type Metadata struct {
NoTOC bool
}
// TemplateSet is the bundle of files written to the per-call scratch dir for an
// HTML render: the chosen doctype template (Name) plus every partial it may
// include. pandoc resolves `$partial()$` includes from the template's own
// directory, so Files must contain Name and all referenced partials.
type TemplateSet struct {
Name string // primary template filename, e.g. "report.html"
Files map[string][]byte // base filename -> bytes (must include Name)
}
// DefaultTemplateSet returns the baked-in template set for doctype `name`
// (e.g. "report"). An empty or unknown name falls back to DefaultTemplateName.
// The set includes every embedded partial so `$..()$` includes resolve; handlers
// may overlay .zddc.d/templates/ overrides onto the returned Files map.
func DefaultTemplateSet(name string) TemplateSet {
files := embeddedTemplateFiles()
primary := name + ".html"
if name == "" || files[primary] == nil {
primary = DefaultTemplateName + ".html"
}
return TemplateSet{Name: primary, Files: files}
}
// Default binary names. The runtime image installs WRAPPER scripts at
// /usr/local/bin/pandoc and /usr/local/bin/chromium-browser (shadowing
// the real binaries in /usr/bin/) so these names resolve through the
@ -146,23 +168,27 @@ func ToDocx(ctx context.Context, source []byte, m Metadata) ([]byte, error) {
return r.Run(ctx, currentPandocBinary(), source, "", cmd)
}
// ToHTML renders source markdown to standalone HTML using
// viewer-template.html. Embeds CSS + images via --embed-resources.
// Template + custom.css live in a per-call scratch dir; the host
// path is passed via ZDDC_SCRATCH so the wrapper bind-mounts it
// into the sandbox at the same path.
func ToHTML(ctx context.Context, source []byte, m Metadata) ([]byte, error) {
// ToHTML renders source markdown to standalone HTML using the doctype
// template in ts. Embeds CSS + images via --embed-resources. The
// template + its partials live in a per-call scratch dir; the host path
// is passed via ZDDC_SCRATCH so the wrapper bind-mounts it into the
// sandbox at the same path. A zero-value ts falls back to the embedded
// default template.
func ToHTML(ctx context.Context, source []byte, m Metadata, ts TemplateSet) ([]byte, error) {
r := currentRunner()
if r == nil {
return nil, ErrUnavailable
}
scratch, err := writeAssetsToScratch(currentScratchDir())
if ts.Name == "" || len(ts.Files) == 0 {
ts = DefaultTemplateSet(DefaultTemplateName)
}
scratch, err := writeTemplateSetToScratch(currentScratchDir(), ts)
if err != nil {
return nil, fmt.Errorf("scratch: %w", err)
}
defer os.RemoveAll(scratch)
tplPath := filepath.Join(scratch, "viewer-template.html")
tplPath := filepath.Join(scratch, ts.Name)
cmd := []string{
"--from=markdown+yaml_metadata_block",
"--to=html5",
@ -182,18 +208,18 @@ func ToHTML(ctx context.Context, source []byte, m Metadata) ([]byte, error) {
}
// ToPDF renders source markdown to PDF in two stages: pandoc
// produces HTML using viewer-template.html (stage 1), then headless
// chromium prints that HTML to PDF (stage 2). The two-stage choice
// preserves the print-media CSS already authored in viewer-
// template.html — pandoc's native --pdf-engine path uses LaTeX
// which would bypass it entirely.
// produces HTML using the doctype template in ts (stage 1), then
// headless chromium prints that HTML to PDF (stage 2). The two-stage
// choice preserves the print-media CSS authored in the templates —
// pandoc's native --pdf-engine path uses LaTeX which would bypass it
// entirely.
//
// Both stages share a single per-call scratch dir: pandoc writes
// `in.html` and chromium reads it, then chromium writes `out.pdf`
// which the host reads back. The wrapper bind-mounts the scratch
// dir read-write into the sandbox at the same path.
func ToPDF(ctx context.Context, source []byte, m Metadata) ([]byte, error) {
html, err := ToHTML(ctx, source, m)
func ToPDF(ctx context.Context, source []byte, m Metadata, ts TemplateSet) ([]byte, error) {
html, err := ToHTML(ctx, source, m, ts)
if err != nil {
return nil, err
}

10
zddc/internal/convert/convert_test.go
View file

@ -86,7 +86,7 @@ func TestToHTML_UsesTemplateFromScratchDir(t *testing.T) {
t.Cleanup(func() { InstallRunner(nil) })
SetBinaries("pandoc", "chromium-browser")
_, err := ToHTML(context.Background(), []byte("# Hi\n"), Metadata{Title: "Hi"})
_, err := ToHTML(context.Background(), []byte("# Hi\n"), Metadata{Title: "Hi"}, TemplateSet{})
if err != nil {
t.Fatalf("ToHTML: %v", err)
}
@ -101,7 +101,7 @@ func TestToHTML_UsesTemplateFromScratchDir(t *testing.T) {
if scratch == "" {
t.Fatalf("ToHTML must pass a scratch dir to the runner")
}
wantTpl := "--template=" + scratch + "/viewer-template.html"
wantTpl := "--template=" + scratch + "/report.html"
if !contains(call, wantTpl) {
t.Errorf("template flag missing/wrong; want %q in %v", wantTpl, call)
}
@ -115,7 +115,7 @@ func TestToHTML_NoTOCSuppressesTOC(t *testing.T) {
InstallRunner(f)
t.Cleanup(func() { InstallRunner(nil) })
_, _ = ToHTML(context.Background(), []byte("# Hi\n"), Metadata{NoTOC: true})
_, _ = ToHTML(context.Background(), []byte("# Hi\n"), Metadata{NoTOC: true}, TemplateSet{})
_, call := f.lastCall()
if contains(call, "--toc") {
t.Errorf("TOC should be suppressed when NoTOC=true: %v", call)
@ -170,7 +170,7 @@ func TestScratchDir_UsedByToHTML(t *testing.T) {
scratchRoot := t.TempDir()
SetScratchDir(scratchRoot)
_, err := ToHTML(context.Background(), []byte("# Hi\n"), Metadata{})
_, err := ToHTML(context.Background(), []byte("# Hi\n"), Metadata{}, TemplateSet{})
if err != nil {
t.Fatalf("ToHTML: %v", err)
}
@ -199,7 +199,7 @@ func TestToPDF_TwoStagePipeline(t *testing.T) {
t.Cleanup(func() { InstallRunner(nil) })
SetBinaries("pandoc", "chromium-browser")
_, err := ToPDF(context.Background(), []byte("# Hi\n"), Metadata{})
_, err := ToPDF(context.Background(), []byte("# Hi\n"), Metadata{}, TemplateSet{})
// PDF read-back will fail (fake runner didn't write the file) —
// that's expected for this test which only inspects the call shape.
if err == nil {

163
zddc/internal/convert/custom.css
View file

@ -1,163 +0,0 @@
/*
* Legal-style heading numbering for ZDDC documents
* Adds hierarchical numbering like 1, 1.1, 1.1.1, etc.
*/
/* Reset counters at document level */
.document-content {
counter-reset: h1-counter;
}
/* H1 counters */
h1 {
counter-reset: h2-counter h3-counter h4-counter h5-counter h6-counter;
counter-increment: h1-counter;
}
h1::before {
content: counter(h1-counter) ". ";
font-weight: bold;
color: var(--primary-color);
}
/* H2 counters */
h2 {
counter-reset: h3-counter h4-counter h5-counter h6-counter;
counter-increment: h2-counter;
}
h2::before {
content: counter(h1-counter) "." counter(h2-counter) " ";
font-weight: bold;
color: var(--primary-color);
}
/* H3 counters */
h3 {
counter-reset: h4-counter h5-counter h6-counter;
counter-increment: h3-counter;
}
h3::before {
content: counter(h1-counter) "." counter(h2-counter) "." counter(h3-counter) " ";
font-weight: bold;
color: var(--primary-color);
}
/* H4 counters */
h4 {
counter-reset: h5-counter h6-counter;
counter-increment: h4-counter;
}
h4::before {
content: counter(h1-counter) "." counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) " ";
font-weight: bold;
color: var(--primary-color);
}
/* H5 counters */
h5 {
counter-reset: h6-counter;
counter-increment: h5-counter;
}
h5::before {
content: counter(h1-counter) "." counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) "." counter(h5-counter) " ";
font-weight: bold;
color: var(--primary-color);
}
/* H6 counters */
h6 {
counter-increment: h6-counter;
}
h6::before {
content: counter(h1-counter) "." counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) "." counter(h5-counter) "." counter(h6-counter) " ";
font-weight: bold;
color: var(--primary-color);
}
/* TOC numbering to match document headings */
.toc {
counter-reset: toc-h1;
}
.toc ul {
list-style: none;
}
.toc > ul > li {
counter-increment: toc-h1;
counter-reset: toc-h2 toc-h3 toc-h4 toc-h5 toc-h6;
}
.toc > ul > li > a::before {
content: counter(toc-h1) ". ";
font-weight: bold;
color: var(--primary-color);
margin-right: 0.25em;
}
.toc > ul > li > ul > li {
counter-increment: toc-h2;
counter-reset: toc-h3 toc-h4 toc-h5 toc-h6;
}
.toc > ul > li > ul > li > a::before {
content: counter(toc-h1) "." counter(toc-h2) " ";
font-weight: bold;
color: var(--primary-color);
margin-right: 0.25em;
}
.toc > ul > li > ul > li > ul > li {
counter-increment: toc-h3;
counter-reset: toc-h4 toc-h5 toc-h6;
}
.toc > ul > li > ul > li > ul > li > a::before {
content: counter(toc-h1) "." counter(toc-h2) "." counter(toc-h3) " ";
font-weight: bold;
color: var(--primary-color);
margin-right: 0.25em;
}
/* Optional: Add some spacing after the numbers */
h1::before, h2::before, h3::before, h4::before, h5::before, h6::before {
margin-right: 0.5em;
}
/* Print-specific adjustments */
@media print {
h1::before, h2::before, h3::before, h4::before, h5::before, h6::before {
color: #000 !important; /* Ensure numbers print in black */
}
}
/* Optional: Style adjustments for better visual hierarchy */
h1 {
border-bottom: 2px solid var(--primary-color);
padding-bottom: 0.3em;
margin-top: 1em;
}
/* Reduce margin for first heading */
h1:first-of-type {
margin-top: 0.5em;
}
h2 {
border-bottom: 1px solid var(--border-color);
padding-bottom: 0.2em;
margin-top: 1.5em;
}
h3 {
margin-top: 1.2em;
}
h4, h5, h6 {
margin-top: 1em;
}

87
zddc/internal/convert/embed.go
View file

@ -1,19 +1,80 @@
package convert
import _ "embed"
import (
"embed"
"io/fs"
"path"
"sort"
)
// Pandoc HTML template and its companion stylesheet, copied verbatim from
// /pandoc/viewer-template.html and /pandoc/custom.css. The runner writes
// these to a host scratch dir on each conversion and bind-mounts them
// read-only into the container so pandoc can `--template` against them.
// Default pandoc HTML templates, mirrored verbatim from /pandoc/templates/ by
// the top-level ./build (shared/build-lib.sh: sync_pandoc_templates). The runner
// writes the chosen template + its partials to a host scratch dir on each HTML
// conversion and bind-mounts them into the sandbox so pandoc can `--template`
// against them.
//
// Refresh: when /pandoc/viewer-template.html changes, copy the new bytes
// here. There's no symlink because go:embed paths must resolve under the
// containing module — and we want the binary to ship the bytes verbatim,
// not depend on the source tree at runtime.
// pandoc/templates/ is the single source of truth; this directory is a build
// artifact kept in sync and guarded by TestEmbeddedTemplatesMatchSource. There's
// no symlink because go:embed paths must resolve under the containing module, and
// we want the binary to ship the bytes verbatim, not depend on the source tree at
// runtime.
//
// The set holds named doctype templates (report.html, letter.html,
// specification.html) plus the shared partials they include (_head.html,
// _doc.html, _scripts.html). A document picks one via its `template:` front
// matter; operators override individual files through the .zddc.d/templates/
// cascade (see internal/handler).
//go:embed viewer-template.html
var viewerTemplate []byte
// `all:` is required so the `_`-prefixed partials (_head.html, _doc.html,
// _scripts.html) are embedded — a bare `//go:embed templates` excludes names
// beginning with `_` or `.`.
//
//go:embed all:templates
var templatesFS embed.FS
//go:embed custom.css
var customCSS []byte
// DefaultTemplateName is used when a document declares no `template:` field or
// names one that doesn't resolve.
const DefaultTemplateName = "report"
// embeddedTemplate returns the bytes of a baked-in template/partial by base file
// name (e.g. "report.html", "_head.html"), or nil if there is no such default.
func embeddedTemplate(name string) []byte {
b, err := templatesFS.ReadFile(path.Join("templates", name))
if err != nil {
return nil
}
return b
}
// embeddedTemplateFiles returns all baked-in template/partial files keyed by
// base name. The returned map is a fresh copy the caller may mutate (e.g. to
// overlay .zddc.d/templates overrides).
func embeddedTemplateFiles() map[string][]byte {
out := make(map[string][]byte)
entries, _ := fs.ReadDir(templatesFS, "templates")
for _, e := range entries {
if e.IsDir() {
continue
}
if b := embeddedTemplate(e.Name()); b != nil {
out[e.Name()] = b
}
}
return out
}
// EmbeddedTemplateNames lists the baked-in doctype template names (no extension,
// partials excluded — i.e. the names a `template:` field may select), sorted.
func EmbeddedTemplateNames() []string {
var names []string
entries, _ := fs.ReadDir(templatesFS, "templates")
for _, e := range entries {
n := e.Name()
if e.IsDir() || n == "" || n[0] == '_' || path.Ext(n) != ".html" {
continue
}
names = append(names, n[:len(n)-len(".html")])
}
sort.Strings(names)
return names
}

28
zddc/internal/convert/runner.go
View file

@ -274,29 +274,27 @@ func (r *ringWriter) String() string {
return string(r.buf)
}
// writeAssetsToScratch materialises the embedded viewer-template.html
// and custom.css into a fresh scratch dir and returns the host path.
// Caller is responsible for os.RemoveAll(dir) when done. Used by
// ToHTML which needs the template visible inside the sandbox.
// writeTemplateSetToScratch materialises a TemplateSet (the chosen doctype
// template plus its partials) into a fresh scratch dir and returns the host
// path. Caller is responsible for os.RemoveAll(dir) when done. Used by ToHTML,
// which needs the template + partials visible inside the sandbox (pandoc
// resolves `$partial()$` includes from the template's own directory).
//
// scratchRoot controls where the temp dir lands. Empty means
// "use $TMPDIR".
// scratchRoot controls where the temp dir lands. Empty means "use $TMPDIR".
//
// Files are written world-readable so the binary's default user can
// read them through the wrapper's bind mount regardless of the
// host's umask.
func writeAssetsToScratch(scratchRoot string) (string, error) {
// Files are written world-readable so the binary's default user can read them
// through the wrapper's bind mount regardless of the host's umask. File names
// are base names only (no path separators) — they all land flat in the dir.
func writeTemplateSetToScratch(scratchRoot string, ts TemplateSet) (string, error) {
dir, err := os.MkdirTemp(scratchRoot, "zddc-convert-")
if err != nil {
return "", fmt.Errorf("scratch dir: %w", err)
}
if err := os.WriteFile(filepath.Join(dir, "viewer-template.html"), viewerTemplate, 0o644); err != nil {
for name, b := range ts.Files {
if err := os.WriteFile(filepath.Join(dir, filepath.Base(name)), b, 0o644); err != nil {
os.RemoveAll(dir)
return "", fmt.Errorf("write template: %w", err)
return "", fmt.Errorf("write template %q: %w", name, err)
}
if err := os.WriteFile(filepath.Join(dir, "custom.css"), customCSS, 0o644); err != nil {
os.RemoveAll(dir)
return "", fmt.Errorf("write css: %w", err)
}
if err := chmodTree(dir, 0o755, 0o644); err != nil {
os.RemoveAll(dir)

112
zddc/internal/convert/templates/_doc.html Normal file
View file

@ -0,0 +1,112 @@
<div class="app-container">
$if(toc)$
<!-- Sidebar Navigation -->
<aside id="sidebar" role="complementary" aria-label="Table of contents">
<header class="sidebar-header">
<div class="toc-header-row">
<div class="sidebar-title">Table Of Contents</div>
<div class="toc-level-selector">
<select id="toc-level" aria-label="Filter table of contents levels">
<option value="1">1</option>
<option value="2">2</option>
<option value="3" selected>3</option>
<option value="4">4</option>
<option value="5">5</option>
<option value="6">6</option>
</select>
</div>
</div>
</header>
<div class="toc-container">
$if(toc)$
<nav class="toc" role="navigation" aria-label="Table of contents">
$toc$
</nav>
$endif$
</div>
</aside>
$endif$
<!-- Main Content Area -->
<main class="content-wrapper" role="main">
<div class="content-page">
<!-- Document Header -->
<header class="document-header">
$if(toc)$
<div class="mobile-menu-container">
<button class="mobile-menu-toggle" type="button" aria-label="Toggle navigation menu" aria-expanded="false">
<span aria-hidden="true">☰</span>
</button>
</div>
$endif$
<div class="header-content">
$if(client)$$if(project)$
<div class="header-line client-project">
$client$ - $project$$if(project_number)$ ($project_number$)$endif$
</div>
$endif$$endif$
$if(title)$
<div class="document-title">$title$</div>
$endif$
<div class="document-meta">
$if(tracking_number)$<span class="tracking-number">$tracking_number$</span>$endif$
$if(revision)$<span class="revision">Revision: $revision$</span>$endif$
$if(status)$<span class="status">Status: $status$</span>$endif$
$if(revision_comparison)$<span class="revision-comparison">$revision_comparison$</span>$endif$
</div>
$if(is_draft)$
$if(generation_time)$
<div class="draft-line">
<span class="draft-status">[DRAFT Generated at $generation_time$]</span>
</div>
$endif$
$endif$
</div>
</header>
<!-- Scroll Progress Bar -->
<div class="scroll-progress" role="progressbar" aria-label="Reading progress">
<div class="scroll-progress-bar"></div>
</div>
<!-- Print-only header -->
<div class="print-header">
$if(custom_header)$
$custom_header$
$else$
$if(client)$$if(project)$
<div class="header-line client-project">
$client$ - $project$$if(project_number)$ ($project_number$)$endif$
</div>
$endif$$endif$
$if(title)$
<div class="header-line document-title">$title$</div>
$endif$
$if(tracking_number)$<div class="header-line">$tracking_number$$if(revision)$ Revision: $revision$$endif$$if(status)$ Status: $status$$endif$</div>$endif$
$if(revision_comparison)$<div class="header-line revision-comparison">$revision_comparison$</div>$endif$
$endif$
$if(generation_time)$
<div class="header-line metadata-line draft-line">
<span class="draft-status">Generated: $generation_time$</span>
</div>
$endif$
</div>
<!-- Print-only footer -->
<div class="print-footer">
<div class="footer-left">
$if(tracking_number)$$tracking_number$$endif$$if(revision)$ Revision: $revision$$endif$$if(status)$ Status: $status$$endif$
</div>
<div class="footer-right">
Page <span class="page-number"></span>
</div>
</div>
<!-- Document Content -->
<article class="document-content">
$body$
</article>
</div>
</main>
</div>

778
zddc/internal/convert/templates/_head.html Normal file
View file

@ -0,0 +1,778 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>$if(title)$$title$$else$Document$endif$</title>
<!-- Document metadata for JavaScript -->
$if(revision)$<meta name="revision" content="$revision$">$endif$
$if(generation_time)$<meta name="generation_time" content="$generation_time$">$endif$
<!-- Embedded CSS -->
<style>
/*
* ZDDC Document Viewer Template
* Enhanced responsive layout with TOC navigation
*/
/* CSS Variables for theming - Soft Light Theme */
:root {
--primary-color: #2563eb;
--primary-color-dark: #1d4ed8;
--text-color: #4b5563;
--text-secondary: #6b7280;
--text-primary: #1f2937;
--bg-primary: #f8fafc;
--bg-secondary: #f1f5f9;
--border-color: #d1d5db;
--hover-bg: #e2e8f0;
--active-bg: rgba(37, 99, 235, 0.1);
--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
--sidebar-width: 280px;
--header-height: 120px;
--content-max-width: 900px;
}
/* Dark mode variables - Standard Dark Theme */
@media (prefers-color-scheme: dark) {
:root {
--primary-color: #60a5fa;
--primary-color-dark: #3b82f6;
--text-color: #d1d5db;
--text-secondary: #9ca3af;
--text-primary: #f9fafb;
--bg-primary: #111827;
--bg-secondary: #1f2937;
--border-color: #374151;
--hover-bg: #374151;
--active-bg: rgba(96, 165, 250, 0.2);
--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.3);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.4), 0 2px 4px -1px rgba(0, 0, 0, 0.3);
}
}
/* Reset and base styles */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
html {
scroll-behavior: smooth;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
line-height: 1.6;
color: var(--text-color);
background: var(--bg-secondary);
height: 100vh;
overflow-x: hidden;
}
@media print {
body {
height: auto !important;
overflow: visible !important;
}
}
/* App Container - Modern CSS Grid Layout */
.app-container {
height: 100vh;
display: grid;
grid-template-columns: var(--sidebar-width) 1fr;
grid-template-areas: "sidebar main";
}
@media (max-width: 768px) {
.app-container {
grid-template-columns: 1fr;
grid-template-areas: "main";
}
}
/* Content wrapper - Grid area */
.content-wrapper {
grid-area: main;
display: flex;
flex-direction: column;
min-height: 0;
max-width: min(900px, 100%);
margin: 0;
container-type: inline-size;
}
/* Content page simplified */
.content-page {
flex: 1;
display: flex;
flex-direction: column;
}
.header-content {
flex: 1;
display: flex;
flex-direction: column;
justify-content: flex-start;
}
/* Sidebar Navigation - Grid area */
#sidebar {
grid-area: sidebar;
height: 100vh;
background: var(--bg-primary);
border-inline-end: 1px solid var(--border-color);
display: flex;
flex-direction: column;
overflow: hidden;
}
@media (max-width: 768px) {
#sidebar {
position: fixed;
inset: 0;
z-index: 1000;
transform: translateX(-100%);
transition: transform 0.3s ease;
box-shadow: 2px 0 10px rgba(0, 0, 0, 0.1);
background: var(--bg-primary);
}
#sidebar.mobile-open {
transform: translateX(0);
}
.content-wrapper {
max-width: none;
}
/* Ensure mobile TOC uses light theme colors */
#sidebar .sidebar-header {
background: var(--bg-secondary);
color: var(--text-primary);
}
#sidebar .toc a {
color: var(--text-primary);
}
#sidebar .toc a:hover {
background: var(--hover-bg);
}
}
/* Document Header - Flex Row Layout */
.document-header {
background: var(--bg-primary);
border-bottom: 1px solid var(--border-color);
padding: 1rem;
margin-bottom: 0;
display: flex;
align-items: center;
gap: 1rem;
flex-shrink: 0;
}
.mobile-menu-container {
display: none;
flex-shrink: 0;
}
@media (max-width: 768px) {
.mobile-menu-container {
display: flex;
align-items: center;
}
.mobile-menu-toggle {
background: var(--primary-color);
color: white;
border: none;
padding: 0.75rem;
border-radius: 0.5rem;
font-size: 1.2rem;
cursor: pointer;
transition: all 0.2s ease;
line-height: 1;
}
.mobile-menu-toggle:hover {
background: var(--primary-color-dark);
transform: scale(1.05);
margin: 0;
}
}
.header-content {
flex: 1;
min-width: 0;
}
.sidebar-title {
font-size: 1.1rem;
font-weight: 600;
color: var(--text-primary);
margin: 0;
}
.sidebar-header {
padding: 1.25rem 1.5rem;
border-bottom: 1px solid var(--border-color);
background: var(--bg-secondary);
}
.toc-header-row {
display: flex;
justify-content: space-between;
align-items: center;
}
.toc-level-selector {
display: flex;
align-items: center;
gap: 0.5rem;
}
.toc-level-selector select {
padding: 0.25rem 0.5rem;
border: 1px solid var(--border-color);
border-radius: 0.25rem;
background: var(--bg-primary);
color: var(--text-color);
font-size: 0.9rem;
}
/* TOC Container */
.toc-container {
flex: 1;
overflow-y: auto;
padding: 1rem 0;
scrollbar-width: thin;
scrollbar-color: var(--border-color) transparent;
position: relative;
}
.toc-container::-webkit-scrollbar {
width: 6px;
}
.toc-container::-webkit-scrollbar-track {
background: transparent;
}
.toc-container::-webkit-scrollbar-thumb {
background: var(--border-color);
border-radius: 3px;
}
/* Scroll Progress Indicator */
.scroll-progress {
width: 100%;
height: 3px;
background: var(--border-color);
margin-bottom: 20px;
}
.scroll-progress-bar {
height: 100%;
background: var(--primary-color);
width: 0%;
transition: width 0.1s ease;
}
/* TOC Styling */
.toc ul {
list-style: none;
padding: 0;
margin: 0;
}
.toc ul ul {
padding-left: 1.25rem;
margin-top: 0.25rem;
border-left: 2px solid var(--border-color);
margin-left: 0.5rem;
}
.toc li {
margin: 0;
}
.toc a {
display: block;
padding: 0.375rem 0.75rem;
color: var(--text-color);
text-decoration: none;
border-radius: 4px;
transition: all 0.2s ease;
font-size: 0.9rem;
line-height: 1.3;
}
.toc li li a {
border-left: none;
}
.toc a:hover {
background: var(--hover-bg);
color: var(--primary-color);
}
.toc a.active {
background: var(--active-bg);
color: var(--primary-color);
border-left-color: var(--primary-color);
font-weight: 500;
}
/* Content Page Container - Simplified */
.content-page {
flex: 1;
background: var(--bg-primary);
display: flex;
flex-direction: column;
min-height: 0;
}
/* Document Content */
.document-content {
flex: 1;
padding: 0.5rem 2rem 2rem 2rem;
max-width: var(--content-max-width);
margin: 0 auto;
overflow-y: auto;
position: relative;
}
/* Document Header */
.document-header {
border-bottom: 1px solid var(--border-color);
padding: 0.75rem 2rem;
background: var(--bg-primary);
}
.header-content {
max-width: var(--content-max-width);
margin: 0 auto;
}
.header-line {
margin: 0;
line-height: 1.3;
}
/* Header line hierarchy */
.client-project {
font-size: 1.2rem;
color: var(--text-color);
font-weight: 600;
margin-bottom: 0.5rem;
}
.document-title {
font-size: 2.2rem;
font-weight: 700;
color: var(--text-primary);
margin-bottom: 0.5rem;
}
.metadata-line {
font-size: 0.9rem;
color: var(--text-secondary);
font-weight: 400;
}
.draft-status {
color: #dc3545;
font-weight: bold;
margin-left: 0.5rem;
}
/* Print-only elements - hidden on screen */
.print-header,
.print-footer {
display: none;
}
/* Mobile menu backdrop */
@media (max-width: 768px) {
.mobile-menu-container {
display: flex;
align-items: center;
}
#sidebar.mobile-open::before {
content: '';
position: fixed;
top: 0;
left: 0;
right: 0;
bottom: 0;
background: rgba(0, 0, 0, 0.5);
z-index: -1;
}
}
/* Typography */
h1, h2, h3, h4, h5, h6 {
color: var(--text-primary);
font-weight: 600;
line-height: 1.25;
margin-top: 1em;
margin-bottom: 0.5em;
}
/* Remove top margin from first heading in content */
.document-content h1:first-child,
.document-content h2:first-child,
.document-content h3:first-child,
.document-content h4:first-child,
.document-content h5:first-child,
.document-content h6:first-child {
margin-top: 0;
}
h1 { font-size: 2rem; }
h2 { font-size: 1.5rem; }
h3 { font-size: 1.25rem; }
h4 { font-size: 1.125rem; }
h5 { font-size: 1rem; }
h6 { font-size: 0.875rem; }
p {
margin: 1rem 0;
color: var(--text-color);
}
/* Lists */
ol, ul {
margin: 1rem 0;
padding-left: 2rem;
}
ol {
list-style-type: decimal;
}
ul {
list-style-type: disc;
}
li {
margin: 0.25rem 0;
color: var(--text-color);
}
/* Nested lists */
ol ol, ul ul, ol ul, ul ol {
margin: 0.25rem 0;
padding-left: 1.5rem;
}
ul ul {
list-style-type: circle;
}
ul ul ul {
list-style-type: square;
}
/* Tables */
table {
width: 100%;
border-collapse: collapse;
margin: 1.5rem 0;
font-size: 0.9rem;
}
th, td {
padding: 0.75rem;
text-align: left;
border-bottom: 1px solid var(--border-color);
}
/* Print styles */
@media print {
/* Hide online-only elements */
.sidebar,
.mobile-menu-toggle,
.scroll-progress,
.document-header {
display: none !important;
}
/* Show print-only elements */
.print-header {
display: block !important;
position: fixed;
top: 0;
left: 0;
right: 0;
background: white;
border-bottom: 1pt solid #000;
padding: 12pt 0.5in;
z-index: 1000;
margin: 0;
}
.print-footer {
display: flex !important;
position: fixed;
bottom: 0;
left: 0;
right: 0;
background: white;
border-top: 1pt solid #000;
padding: 8pt 0.5in;
z-index: 1000;
justify-content: space-between;
align-items: center;
margin: 0;
}
/* Print header styling */
.print-header .client-project {
font-size: 12pt;
color: #333;
font-weight: 600;
margin: 0 0 4pt 0;
line-height: 1.2;
}
.print-header .document-title {
font-size: 16pt;
color: #000;
font-weight: 700;
margin: 0;
line-height: 1.2;
}
/* Print footer styling */
.print-footer .footer-left,
.print-footer .footer-right {
font-size: 10pt;
color: #666;
margin: 0;
}
/* Page counter for print */
.print-footer .page-number::after {
content: counter(page);
}
@page {
margin: 1in;
size: letter;
counter-increment: page;
}
.draft-line {
margin-top: 4pt;
font-size: 10pt;
}
/* Layout adjustments */
html, body {
width: 100% !important;
max-width: 100% !important;
margin: 0 !important;
}
.app-container {
display: block !important;
width: 100% !important;
max-width: 100% !important;
}
.content-wrapper {
margin-left: 0 !important;
width: 100% !important;
/* The screen layout caps content-wrapper at 900px; in print, the
printable area is page-width minus @page margins (~6.5in =
~624px for letter at 96dpi), which is narrower than 900px BUT
chromium's --print-to-pdf renders at the full page width and
only clips at print time — so without max-width:none the
element extends past the right margin. */
max-width: none !important;
}
.content-page {
max-width: none !important;
width: 100% !important;
padding: 0 !important;
}
.document-content {
margin-top: 80pt !important;
margin-bottom: 50pt !important;
padding: 0 0.5in !important;
border-left: none !important;
min-height: calc(100vh - 130pt) !important;
max-width: 100% !important;
box-sizing: border-box !important;
}
/* Wide content that wouldn't otherwise wrap: tables, code blocks,
long URLs in inline code. Force them to stay within the
printable area instead of running off the right edge. */
pre, code, table, blockquote, img, video {
max-width: 100% !important;
overflow-wrap: break-word !important;
word-wrap: break-word !important;
}
pre {
white-space: pre-wrap !important;
word-break: break-word !important;
}
table {
table-layout: fixed !important;
width: 100% !important;
}
/* Fix list formatting in print */
ol, ul {
padding-left: 2rem !important;
}
li {
margin: 0.25rem 0 !important;
}
/* Typography for print */
body {
font-size: 12pt !important;
line-height: 1.4 !important;
color: #000 !important;
background: white !important;
}
/* Page breaks */
h1, h2, h3, h4, h5, h6 {
page-break-after: avoid;
page-break-inside: avoid;
margin-top: 0.5em;
}
p, li {
orphans: 3;
widows: 3;
page-break-inside: avoid;
}
/* Prevent content cutoff */
* {
box-sizing: border-box;
}
/* Ensure proper spacing at page breaks */
h1:first-child, h2:first-child, h3:first-child {
margin-top: 0;
padding-top: 0.5em;
}
/* Table print formatting */
table {
page-break-inside: avoid;
}
thead {
display: table-header-group;
}
tbody {
display: table-row-group;
}
tr {
page-break-inside: avoid;
}
th, td {
padding: 8pt 6pt !important;
vertical-align: top;
}
a {
color: #000 !important;
text-decoration: underline !important;
}
}
/* Diff styling for pandiff output */
u {
background-color: #d4edda;
color: #155724;
text-decoration: none;
padding: 0.1em 0.2em;
border-radius: 0.2em;
}
/*
* Legal-style heading numbering for ZDDC documents.
* Gated by the `numbered` body class, which the per-doctype templates add when
* the document's YAML front matter sets `numbering: true` (default: off).
*/
body.numbered .document-content { counter-reset: h1-counter; }
body.numbered h1 { counter-reset: h2-counter h3-counter h4-counter h5-counter h6-counter; counter-increment: h1-counter; }
body.numbered h1::before { content: counter(h1-counter) ". "; font-weight: bold; color: var(--primary-color); }
body.numbered h2 { counter-reset: h3-counter h4-counter h5-counter h6-counter; counter-increment: h2-counter; }
body.numbered h2::before { content: counter(h1-counter) "." counter(h2-counter) " "; font-weight: bold; color: var(--primary-color); }
body.numbered h3 { counter-reset: h4-counter h5-counter h6-counter; counter-increment: h3-counter; }
body.numbered h3::before { content: counter(h1-counter) "." counter(h2-counter) "." counter(h3-counter) " "; font-weight: bold; color: var(--primary-color); }
body.numbered h4 { counter-reset: h5-counter h6-counter; counter-increment: h4-counter; }
body.numbered h4::before { content: counter(h1-counter) "." counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) " "; font-weight: bold; color: var(--primary-color); }
body.numbered h5 { counter-reset: h6-counter; counter-increment: h5-counter; }
body.numbered h5::before { content: counter(h1-counter) "." counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) "." counter(h5-counter) " "; font-weight: bold; color: var(--primary-color); }
body.numbered h6 { counter-increment: h6-counter; }
body.numbered h6::before { content: counter(h1-counter) "." counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) "." counter(h5-counter) "." counter(h6-counter) " "; font-weight: bold; color: var(--primary-color); }
/* TOC numbering to match document headings */
body.numbered .toc { counter-reset: toc-h1; }
body.numbered .toc ul { list-style: none; }
body.numbered .toc > ul > li { counter-increment: toc-h1; counter-reset: toc-h2 toc-h3 toc-h4 toc-h5 toc-h6; }
body.numbered .toc > ul > li > a::before { content: counter(toc-h1) ". "; font-weight: bold; color: var(--primary-color); margin-right: 0.25em; }
body.numbered .toc > ul > li > ul > li { counter-increment: toc-h2; counter-reset: toc-h3 toc-h4 toc-h5 toc-h6; }
body.numbered .toc > ul > li > ul > li > a::before { content: counter(toc-h1) "." counter(toc-h2) " "; font-weight: bold; color: var(--primary-color); margin-right: 0.25em; }
body.numbered .toc > ul > li > ul > li > ul > li { counter-increment: toc-h3; counter-reset: toc-h4 toc-h5 toc-h6; }
body.numbered .toc > ul > li > ul > li > ul > li > a::before { content: counter(toc-h1) "." counter(toc-h2) "." counter(toc-h3) " "; font-weight: bold; color: var(--primary-color); margin-right: 0.25em; }
body.numbered h1::before, body.numbered h2::before, body.numbered h3::before,
body.numbered h4::before, body.numbered h5::before, body.numbered h6::before { margin-right: 0.5em; }
@media print {
body.numbered h1::before, body.numbered h2::before, body.numbered h3::before,
body.numbered h4::before, body.numbered h5::before, body.numbered h6::before { color: #000 !important; }
}
/* Visual heading hierarchy that accompanies the numbered/legal look. */
body.numbered h1 { border-bottom: 2px solid var(--primary-color); padding-bottom: 0.3em; margin-top: 1em; }
body.numbered h1:first-of-type { margin-top: 0.5em; }
body.numbered h2 { border-bottom: 1px solid var(--border-color); padding-bottom: 0.2em; margin-top: 1.5em; }
body.numbered h3 { margin-top: 1.2em; }
body.numbered h4, body.numbered h5, body.numbered h6 { margin-top: 1em; }
/*
* Doctype-specific layout. `doctype` comes from the document's YAML front matter
* (report | specification | letter); the per-doctype template sets `doc-<name>`.
* A letter has no TOC sidebar and flows as a normal single column.
*/
body.doc-letter { height: auto; overflow: visible; }
body.doc-letter .content-wrapper { margin: 0 auto; max-width: var(--content-max-width); }
</style>
$for(header-includes)$
$header-includes$
$endfor$
</head>

259
zddc/internal/convert/templates/_scripts.html Normal file
View file

@ -0,0 +1,259 @@
<!-- Embedded JavaScript -->
<script>
'use strict';
// Modern initialization with arrow functions
document.addEventListener('DOMContentLoaded', function() {
// View mode toggle functionality
const buttons = document.querySelectorAll('.view-mode-btn');
const body = document.body;
buttons.forEach(button => {
button.addEventListener('click', function() {
const mode = this.dataset.mode;
// Remove all view mode classes
body.classList.remove('view-original', 'view-final');
// Add the selected mode class (except for diff which is default)
if (mode === 'original') {
body.classList.add('view-original');
} else if (mode === 'final') {
body.classList.add('view-final');
}
// Update button states
buttons.forEach(btn => btn.classList.remove('active'));
this.classList.add('active');
});
});
const sidebar = document.getElementById('sidebar');
if (sidebar) {
initTocNavigation();
}
// Set default TOC level filtering
filterTocLevels('3');
// Setup event listeners with delegation
setupEventListeners();
// Initialize print functionality
initPrintSupport();
});
// Modern TOC Navigation with ES6+ patterns
function initTocNavigation() {
const tocLinks = document.querySelectorAll('.toc a');
const contentArea = document.querySelector('.document-content');
if (!tocLinks.length || !contentArea) return;
// Smooth scroll with event delegation (better performance)
function handleTocClick(e) {
if (!e.target.matches('.toc a')) return;
e.preventDefault();
const href = e.target.getAttribute('href');
const targetId = href ? href.slice(1) : null;
const targetElement = targetId ? document.getElementById(targetId) : null;
if (!targetElement) return;
targetElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
// Update URL hash without adding to browser history
window.location.replace(window.location.pathname + window.location.search + href);
// Update active state
tocLinks.forEach(link => link.classList.remove('active'));
e.target.classList.add('active');
// Close mobile menu if open
const sidebar = document.getElementById('sidebar');
if (sidebar && sidebar.classList.contains('mobile-open')) toggleMobileMenu();
};
document.addEventListener('click', handleTocClick);
// TOC scroll tracking using Intersection Observer API
// NOTE: Intersection Observer is the industry-standard, recommended approach for scroll spy
// implementations as of 2024. It provides better performance (runs off main thread),
// cleaner code, and is supported by all modern browsers. Avoid scroll event listeners
// for this use case as they are performance-intensive and require complex calculations.
// Find all sections with IDs - much simpler approach
const sections = Array.from(contentArea.querySelectorAll('section[id]'));
if (sections.length === 0) {
return;
}
function updateActiveTocItem(activeSection) {
if (!activeSection || !activeSection.id) return;
// Clear all active states
tocLinks.forEach(link => link.classList.remove('active'));
// Find and activate the matching TOC link
const activeLink = document.querySelector('.toc a[href="#' + activeSection.id + '"]');
if (!activeLink) return;
activeLink.classList.add('active');
// Auto-scroll TOC to keep active item visible
activeLink.scrollIntoView({
behavior: 'smooth',
block: 'nearest',
inline: 'nearest'
});
};
// Create Intersection Observer with industry-standard configuration
const observer = new IntersectionObserver(function(entries) {
// Find visible sections and update active TOC item
const visibleSections = entries.filter(function(entry) { return entry.isIntersecting; });
if (visibleSections.length > 0) {
// Sort by position in viewport (topmost first)
visibleSections.sort(function(a, b) { return a.boundingClientRect.top - b.boundingClientRect.top; });
const activeSection = visibleSections[0].target;
updateActiveTocItem(activeSection);
}
}, {
root: contentArea,
rootMargin: '-20% 0px -60% 0px', // Only consider sections in the middle 20% of viewport
threshold: 0.1
});
// Observe all sections
sections.forEach(function(section) { observer.observe(section); });
// Scroll progress bar with throttling for better performance
const progressBar = document.querySelector('.scroll-progress-bar');
if (progressBar) {
let ticking = false;
function updateScrollProgress() {
const scrollTop = contentArea.scrollTop;
const scrollHeight = contentArea.scrollHeight;
const clientHeight = contentArea.clientHeight;
const scrollPercent = scrollHeight > clientHeight
? (scrollTop / (scrollHeight - clientHeight)) * 100
: 0;
progressBar.style.width = Math.min(100, Math.max(0, scrollPercent)) + '%';
ticking = false;
};
function onScroll() {
if (!ticking) {
requestAnimationFrame(updateScrollProgress);
ticking = true;
}
};
contentArea.addEventListener('scroll', onScroll, { passive: true });
updateScrollProgress(); // Initial call
}
};
// Toggle mobile menu with ARIA support
function toggleMobileMenu() {
const sidebar = document.getElementById('sidebar');
const menuToggle = document.querySelector('.mobile-menu-toggle');
if (!sidebar || !menuToggle) return;
const isOpen = sidebar.classList.toggle('mobile-open');
menuToggle.setAttribute('aria-expanded', isOpen.toString());
};
// Filter TOC levels with modern patterns
function filterTocLevels(maxLevel) {
const toc = document.querySelector('.toc');
if (!toc) return;
const allItems = toc.querySelectorAll('li');
const maxLevelNum = parseInt(maxLevel);
const showAll = maxLevel === '6';
allItems.forEach(function(item) {
const link = item.querySelector('a');
if (!link) return;
if (showAll) {
item.style.display = '';
return;
}
// Calculate nesting level more efficiently
let level = 1;
let parent = item.parentElement;
while (parent && !parent.classList.contains('toc')) {
if (parent.tagName === 'LI') level++;
parent = parent.parentElement;
}
item.style.display = level <= maxLevelNum ? '' : 'none';
});
};
// Setup event listeners with delegation
function setupEventListeners() {
// TOC level selector
const tocLevelSelect = document.getElementById('toc-level');
if (tocLevelSelect) tocLevelSelect.addEventListener('change', function(e) {
filterTocLevels(e.target.value);
});
// Mobile menu toggle
const menuToggle = document.querySelector('.mobile-menu-toggle');
if (menuToggle) menuToggle.addEventListener('click', toggleMobileMenu);
// Close mobile menu on outside click
document.addEventListener('click', function(e) {
const sidebar = document.getElementById('sidebar');
const menuToggle = document.querySelector('.mobile-menu-toggle');
if (sidebar && sidebar.classList.contains('mobile-open') &&
!sidebar.contains(e.target) &&
(!menuToggle || !menuToggle.contains(e.target))) {
toggleMobileMenu();
}
});
// Handle escape key to close mobile menu
document.addEventListener('keydown', function(e) {
if (e.key === 'Escape') {
const sidebar = document.getElementById('sidebar');
if (sidebar && sidebar.classList.contains('mobile-open')) {
toggleMobileMenu();
}
}
});
};
// Initialize print support and draft status
function initPrintSupport() {
// Handle draft status for revisions containing tilde (~)
const revision = document.querySelector('meta[name="revision"]');
const generationTime = document.querySelector('meta[name="generation_time"]');
if (revision && generationTime) {
const revisionValue = revision.getAttribute('content');
const timeValue = generationTime.getAttribute('content');
if (revisionValue && revisionValue.includes('~') && timeValue) {
const draftElements = document.querySelectorAll('.draft-status');
draftElements.forEach(function(element) {
element.textContent = ' [DRAFT Generated at ' + timeValue + ']';
});
}
}
}
// Export functions for global access (maintaining backward compatibility)
window.toggleMobileMenu = toggleMobileMenu;
window.filterTocLevels = filterTocLevels;
</script>

56
zddc/internal/convert/templates/letter.html Normal file
View file

@ -0,0 +1,56 @@
<!DOCTYPE html>
<html lang="en">
$_head()$
<body class="doc-letter$if(numbering)$ numbered$endif$">
<!-- Letter layout: single column, no TOC sidebar -->
<main class="content-wrapper" role="main">
<div class="content-page">
<!-- Letterhead -->
<header class="document-header">
<div class="header-content">
$if(client)$$if(project)$
<div class="header-line client-project">
$client$ - $project$$if(project_number)$ ($project_number$)$endif$
</div>
$endif$$endif$
$if(title)$
<div class="document-title">$title$</div>
$endif$
<div class="document-meta">
$if(date)$<span class="date">$date$</span>$endif$
$if(tracking_number)$<span class="tracking-number">$tracking_number$</span>$endif$
$if(revision)$<span class="revision">Revision: $revision$</span>$endif$
$if(status)$<span class="status">Status: $status$</span>$endif$
</div>
</div>
</header>
<!-- Print-only header -->
<div class="print-header">
$if(custom_header)$
$custom_header$
$else$
$if(client)$$if(project)$
<div class="header-line client-project">$client$ - $project$$if(project_number)$ ($project_number$)$endif$</div>
$endif$$endif$
$if(title)$<div class="header-line document-title">$title$</div>$endif$
$endif$
</div>
<!-- Print-only footer -->
<div class="print-footer">
<div class="footer-left">
$if(tracking_number)$$tracking_number$$endif$$if(revision)$ Revision: $revision$$endif$$if(status)$ Status: $status$$endif$
</div>
<div class="footer-right">Page <span class="page-number"></span></div>
</div>
<article class="document-content">
$body$
</article>
</div>
</main>
$_scripts()$
</body>
</html>

9
zddc/internal/convert/templates/report.html Normal file
View file

@ -0,0 +1,9 @@
<!DOCTYPE html>
<html lang="en">
$_head()$
<body class="doc-report$if(numbering)$ numbered$endif$">
$_doc()$
$_scripts()$
</body>
</html>

9
zddc/internal/convert/templates/specification.html Normal file
View file

@ -0,0 +1,9 @@
<!DOCTYPE html>
<html lang="en">
$_head()$
<body class="doc-specification$if(numbering)$ numbered$endif$">
$_doc()$
$_scripts()$
</body>
</html>

71
zddc/internal/convert/templatesync_test.go Normal file
View file

@ -0,0 +1,71 @@
package convert
import (
"os"
"path/filepath"
"testing"
)
// canonicalTemplatesDir is the single source of truth for the conversion
// templates: /pandoc/templates/, relative to this package
// (zddc/internal/convert → ../../../pandoc/templates).
const canonicalTemplatesDir = "../../../pandoc/templates"
// TestEmbeddedTemplatesMatchSource guards against drift between the embedded
// templates/ (a build artifact, synced by shared/build-lib.sh:
// sync_pandoc_templates) and the canonical pandoc/templates/. If this fails,
// re-run ./build (or copy pandoc/templates/* into this package's templates/).
func TestEmbeddedTemplatesMatchSource(t *testing.T) {
srcEntries, err := os.ReadDir(canonicalTemplatesDir)
if err != nil {
t.Fatalf("read canonical templates dir %q: %v", canonicalTemplatesDir, err)
}
embedded := embeddedTemplateFiles()
srcCount := 0
for _, e := range srcEntries {
if e.IsDir() || filepath.Ext(e.Name()) != ".html" {
continue
}
srcCount++
want, err := os.ReadFile(filepath.Join(canonicalTemplatesDir, e.Name()))
if err != nil {
t.Fatalf("read %s: %v", e.Name(), err)
}
got, ok := embedded[e.Name()]
if !ok {
t.Errorf("embedded templates/ is missing %s (run ./build to sync)", e.Name())
continue
}
if string(got) != string(want) {
t.Errorf("embedded %s differs from pandoc/templates/%s (run ./build to sync)", e.Name(), e.Name())
}
}
if srcCount != len(embedded) {
t.Errorf("template count mismatch: canonical=%d embedded=%d (stale file in one tree?)", srcCount, len(embedded))
}
}
// TestDefaultTemplateSet checks the doctype fallback + that partials ride along.
func TestDefaultTemplateSet(t *testing.T) {
for _, name := range EmbeddedTemplateNames() {
ts := DefaultTemplateSet(name)
if ts.Name != name+".html" {
t.Errorf("DefaultTemplateSet(%q).Name = %q, want %q.html", name, ts.Name, name)
}
if ts.Files[ts.Name] == nil {
t.Errorf("DefaultTemplateSet(%q) Files missing primary %q", name, ts.Name)
}
if ts.Files["_head.html"] == nil {
t.Errorf("DefaultTemplateSet(%q) Files missing _head.html partial", name)
}
}
// Unknown / empty fall back to the default doctype.
if ts := DefaultTemplateSet("nope"); ts.Name != DefaultTemplateName+".html" {
t.Errorf("unknown doctype fell back to %q, want %q.html", ts.Name, DefaultTemplateName)
}
if ts := DefaultTemplateSet(""); ts.Name != DefaultTemplateName+".html" {
t.Errorf("empty doctype fell back to %q, want %q.html", ts.Name, DefaultTemplateName)
}
}

1261
zddc/internal/convert/viewer-template.html
View file

File diff suppressed because it is too large Load diff

8
zddc/internal/handler/converthandler.go
View file

@ -135,7 +135,7 @@ func ServeConverted(cfg config.Config, w http.ResponseWriter, r *http.Request, s
// Slow path: convert, cache, serve. Singleflight collapses
// concurrent requests for the same target.
_, err = convertSF.Do(cacheAbs, func() (any, error) {
return nil, buildAndStore(r.Context(), srcAbs, srcInfo, cacheDir, cacheAbs, format, base, chain)
return nil, buildAndStore(r.Context(), cfg.Root, srcAbs, srcInfo, cacheDir, cacheAbs, format, base, chain)
})
if err != nil {
mapConvertError(w, err, format)
@ -148,7 +148,7 @@ func ServeConverted(cfg config.Config, w http.ResponseWriter, r *http.Request, s
// buildAndStore reads the source, runs the conversion, atomically
// writes the result, and syncs the cached mtime to the source mtime.
// Returns the cached file's absolute path on success.
func buildAndStore(ctx context.Context, srcAbs string, srcInfo os.FileInfo, cacheDir, cacheAbs, format, base string, chain zddc.PolicyChain) error {
func buildAndStore(ctx context.Context, fsRoot, srcAbs string, srcInfo os.FileInfo, cacheDir, cacheAbs, format, base string, chain zddc.PolicyChain) error {
source, err := os.ReadFile(srcAbs)
if err != nil {
return fmt.Errorf("read source: %w", err)
@ -164,9 +164,9 @@ func buildAndStore(ctx context.Context, srcAbs string, srcInfo os.FileInfo, cach
case "docx":
out, err = convert.ToDocx(ctx, source, meta)
case "html":
out, err = convert.ToHTML(ctx, source, meta)
out, err = convert.ToHTML(ctx, source, meta, resolveTemplateSet(fsRoot, filepath.Dir(srcAbs), source))
case "pdf":
out, err = convert.ToPDF(ctx, source, meta)
out, err = convert.ToPDF(ctx, source, meta, resolveTemplateSet(fsRoot, filepath.Dir(srcAbs), source))
default:
return fmt.Errorf("unsupported format %q", format)
}

143
zddc/internal/handler/converttemplate.go Normal file
View file

@ -0,0 +1,143 @@
package handler
import (
"bytes"
"os"
"path/filepath"
"strings"
"codeberg.org/VARASYS/ZDDC/zddc/internal/convert"
"gopkg.in/yaml.v3"
)
// resolveTemplateSet builds the convert.TemplateSet for an HTML/PDF render of a
// markdown source. It starts from the baked-in defaults for the doctype named in
// the document's `template:` front matter (default "report"), then overlays any
// per-project / per-party overrides found in the `.zddc.d/templates/` cascade.
//
// The cascade walks from the document's directory up to fsRoot; a nearer level
// (e.g. working/<party>/.zddc.d/templates/) overrides a farther one (e.g.
// working/.zddc.d/templates/), which overrides the embedded default. Overrides
// may replace the named doctype template, any shared partial (_head.html, …), or
// introduce an entirely new doctype the front matter names.
func resolveTemplateSet(fsRoot, docDir string, source []byte) convert.TemplateSet {
name := templateNameFromFrontMatter(source) // "" when absent/invalid
ts := convert.DefaultTemplateSet(name) // primary falls back to report
dirs := templateCascadeDirs(fsRoot, docDir)
// If the named doctype isn't a baked-in default but an override provides it,
// adopt the override as the primary template.
if name != "" {
primary := name + ".html"
if b := firstTemplateOverride(dirs, primary); b != nil {
ts.Name = primary
ts.Files[primary] = b
}
}
// Overlay overrides for every file in the set (primary + partials).
for fname := range ts.Files {
if b := firstTemplateOverride(dirs, fname); b != nil {
ts.Files[fname] = b
}
}
return ts
}
// templateCascadeDirs returns the `<level>/.zddc.d/templates` directories from
// docDir up to fsRoot, nearest (most specific) first. Levels outside fsRoot are
// skipped (path-containment guard).
func templateCascadeDirs(fsRoot, docDir string) []string {
root := filepath.Clean(fsRoot)
d := filepath.Clean(docDir)
var dirs []string
for {
if d == root || strings.HasPrefix(d, root+string(filepath.Separator)) {
dirs = append(dirs, filepath.Join(d, ReservedSidecar, "templates"))
}
if d == root {
break
}
parent := filepath.Dir(d)
if parent == d {
break
}
d = parent
}
return dirs
}
// firstTemplateOverride returns the bytes of the first existing `<dir>/<name>`
// across dirs (nearest first), or nil. name is reduced to a base name so it can
// never escape the templates dir.
func firstTemplateOverride(dirs []string, name string) []byte {
base := filepath.Base(name)
if base == "" || base == "." || base == ".." {
return nil
}
for _, dir := range dirs {
if b, err := os.ReadFile(filepath.Join(dir, base)); err == nil {
return b
}
}
return nil
}
// templateNameFromFrontMatter extracts a sanitized `template:` doctype name from
// a markdown document's leading YAML front matter. Returns "" when there is no
// front matter, no `template:` field, or the value isn't a safe bare name.
func templateNameFromFrontMatter(source []byte) string {
fm := leadingFrontMatter(source)
if fm == nil {
return ""
}
var doc struct {
Template string `yaml:"template"`
}
if err := yaml.Unmarshal(fm, &doc); err != nil {
return ""
}
return sanitizeTemplateName(doc.Template)
}
// leadingFrontMatter returns the YAML between an opening `---` line (which must
// be the very first line) and the next `---` or `...` line, or nil if absent.
func leadingFrontMatter(src []byte) []byte {
s := bytes.TrimPrefix(src, []byte{0xEF, 0xBB, 0xBF}) // strip a UTF-8 BOM
if !bytes.HasPrefix(s, []byte("---\n")) && !bytes.HasPrefix(s, []byte("---\r\n")) {
return nil
}
lines := bytes.Split(s, []byte("\n"))
var buf bytes.Buffer
for i := 1; i < len(lines); i++ {
ln := bytes.TrimRight(lines[i], "\r")
if bytes.Equal(ln, []byte("---")) || bytes.Equal(ln, []byte("...")) {
return buf.Bytes()
}
buf.Write(lines[i])
buf.WriteByte('\n')
}
return nil // unterminated block
}
// sanitizeTemplateName allows only a bare basename of [A-Za-z0-9_-] so a
// `template:` value can't traverse paths or name a partial. Returns "" if the
// value is empty or contains any other character.
func sanitizeTemplateName(name string) string {
name = strings.TrimSpace(name)
if name == "" {
return ""
}
for _, r := range name {
switch {
case r == '-' || r == '_':
case r >= 'a' && r <= 'z':
case r >= 'A' && r <= 'Z':
case r >= '0' && r <= '9':
default:
return ""
}
}
return name
}

95
zddc/internal/handler/converttemplate_test.go Normal file
View file

@ -0,0 +1,95 @@
package handler
import (
"os"
"path/filepath"
"testing"
)
func TestTemplateNameFromFrontMatter(t *testing.T) {
cases := []struct {
name string
src string
want string
}{
{"plain", "---\ntemplate: specification\n---\n\n# H\n", "specification"},
{"quoted", "---\ntemplate: \"letter\"\n---\n", "letter"},
{"absent", "---\ntitle: X\n---\n", ""},
{"no-frontmatter", "# Just a heading\n", ""},
{"traversal-rejected", "---\ntemplate: ../../etc/passwd\n---\n", ""},
{"slash-rejected", "---\ntemplate: a/b\n---\n", ""},
{"crlf", "---\r\ntemplate: report\r\n---\r\n", "report"},
{"dots-terminator", "---\ntemplate: letter\n...\nbody", "letter"},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
if got := templateNameFromFrontMatter([]byte(c.src)); got != c.want {
t.Errorf("templateNameFromFrontMatter(%q) = %q, want %q", c.src, got, c.want)
}
})
}
}
func TestResolveTemplateSet_DefaultsAndCascade(t *testing.T) {
root := t.TempDir()
party := filepath.Join(root, "working", "AcmeCo")
if err := os.MkdirAll(party, 0o755); err != nil {
t.Fatal(err)
}
// No overrides, no front matter → embedded report, partials present.
ts := resolveTemplateSet(root, party, []byte("# Hi\n"))
if ts.Name != "report.html" {
t.Fatalf("default doctype: got %q, want report.html", ts.Name)
}
if ts.Files["_head.html"] == nil {
t.Errorf("partial _head.html missing from default set")
}
embeddedReport := string(ts.Files["report.html"])
// Front matter selects a doctype.
if ts := resolveTemplateSet(root, party, []byte("---\ntemplate: letter\n---\n")); ts.Name != "letter.html" {
t.Errorf("front-matter doctype: got %q, want letter.html", ts.Name)
}
// Project-global override at <root>/.zddc.d/templates/report.html.
projDir := filepath.Join(root, ".zddc.d", "templates")
if err := os.MkdirAll(projDir, 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(projDir, "report.html"), []byte("PROJECT-REPORT"), 0o644); err != nil {
t.Fatal(err)
}
ts = resolveTemplateSet(root, party, []byte("# Hi\n"))
if string(ts.Files["report.html"]) != "PROJECT-REPORT" {
t.Errorf("project override not applied: %q", ts.Files["report.html"])
}
if string(ts.Files["report.html"]) == embeddedReport {
t.Errorf("override identical to embedded — overlay didn't happen")
}
// Party override wins over project-global.
partyDir := filepath.Join(party, ".zddc.d", "templates")
if err := os.MkdirAll(partyDir, 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(partyDir, "report.html"), []byte("PARTY-REPORT"), 0o644); err != nil {
t.Fatal(err)
}
ts = resolveTemplateSet(root, party, []byte("# Hi\n"))
if string(ts.Files["report.html"]) != "PARTY-REPORT" {
t.Errorf("party override should win: got %q", ts.Files["report.html"])
}
// A brand-new doctype provided only as an override is adopted as primary.
if err := os.WriteFile(filepath.Join(partyDir, "memo.html"), []byte("MEMO-TEMPLATE"), 0o644); err != nil {
t.Fatal(err)
}
ts = resolveTemplateSet(root, party, []byte("---\ntemplate: memo\n---\n"))
if ts.Name != "memo.html" || string(ts.Files["memo.html"]) != "MEMO-TEMPLATE" {
t.Errorf("custom doctype override: name=%q bytes=%q", ts.Name, ts.Files["memo.html"])
}
if ts.Files["_head.html"] == nil {
t.Errorf("partials should still ride along with a custom doctype override")
}
}