Scope & Components

Scope

Components

Component Purpose

bin/build-adoc.sh

Primary AsciiDoc builder — HTML, PDF, DOCX, EPUB, Markdown with watch, batch, encrypt, validate, smart build. Auto-detects Antora modules and resolves partial$/example$ includes + antora.yml attributes

bin/doc.sh

Unified router — detects input type (.adoc, .md, .tex, .mmd) and delegates to appropriate backend

bin/publish.sh

Markdown publisher — styled HTML via Pandoc with theme system, AsciiDoc conversion

bin/build-latex.sh

LaTeX builder — multi-pass pdflatex with Mermaid diagram pre-rendering

docinfo/css/

Light variant CSS: code-blocks, admonitions, carved grid tables, inline-code

docinfo/css-dark/

Midnight variant CSS (GitHub Dark palette)

docinfo/css-catppuccin/

Catppuccin Mocha variant CSS (warm dark palette)

docinfo/css-royal/

Royal Blue variant CSS (deep navy + gold accents)

docinfo/js/

Shared JS: copy-button with language label detection

docinfo/compose.sh

Assembles selected CSS variant + JS into single docinfo-footer.html. Accepts --variant light|dark|catppuccin|royal

converters/md2adoc.py

Markdown-to-AsciiDoc converter with YAML frontmatter support

converters/render-mermaid.py

Mermaid diagram pre-renderer for PDF/EPUB (extracts blocks, renders via mmdc)

themes/pdf/

asciidoctor-pdf themes: base, operations, learning, reference, creative, don-quijote, catppuccin

themes/html/

HTML themes: dark-sidebar (full Pandoc theme), asciidoc (lightweight)

themes/epub/

EPUB stylesheets with category color overrides

templates/

LaTeX templates (base, CHLA branding, personal), Markdown templates, AsciiDoc partials

Consumers

  • Principia PKMS (standalone builds of worklogs, captures, runbooks)

  • CHLA private playbook (encrypted ISE deployment docs)

  • Any domus spoke repo needing standalone export (Antora pages auto-resolve)

  • Future: any project needing professional document output

Design Decisions

  • docinfo split: CSS and JS live in separate files for independent iteration; compose.sh assembles them because Asciidoctor requires a single docinfo file

  • Variant system: Each color variant is a directory (css-<name>/) with the same file set. Adding a new variant = create a directory + register in compose.sh

  • Antora auto-detection: Walks up from the input file to find partials/ + pages/ siblings, then resolves partial$ to absolute paths in a temp file. Loads attributes from antora.yml into asciidoctor -a flags. No flag needed

  • $REPO_ROOT resolution: All scripts resolve paths relative to their own location ($SCRIPT_DIR/..), never walking up to find a parent project

  • PDF theme as parameter: --theme operations instead of hardcoded, defaults to base

  • Carved grid tables: All variants use border-separate with visible gridlines, gradient headers, column dividers, and hover glow for a professional spreadsheet-like appearance