Zum Hauptinhalt springen

PDF Generation Toolkit (TOGETHER CCA)

🤖 Generated with Claude Code

⚠️ Not yet reviewed

Co-Authored-By: Claude (noreply@anthropic.com)

Deterministic, brand-aligned PDF generation for proposals and documentation. Markdown in → branded PDF out, using pandoc with the Eisvogel LaTeX template.

Driven by the pdf-generation AI skill, but usable directly from the shell.

Contents​

FilePurpose
install.ps1Install the toolchain (pandoc, MiKTeX/LuaLaTeX, d2) + Roboto fonts via winget
Build-Pdf.ps1Render a Markdown file to a branded PDF
templates/eisvogel.latexEisvogel pandoc LaTeX template
templates/brand-header.texRoboto fonts, brand colors, table/unicode helpers
templates/brand-metadata.yamlShared brand skin (title page, layout, colors)
templates/draft.texOptional DRAFT watermark (-Draft)
templates/together-cca-logo.pngTitle-page logo

Prerequisites​

Run once (installs pandoc, MiKTeX, d2, and the Roboto fonts):

development\pdf\install.ps1

Then open a new shell so the tools land on PATH. MiKTeX installs missing LaTeX packages on first build automatically.

Usage​

# Simplest: PDF next to the source file
development\pdf\Build-Pdf.ps1 -InputPath proposals\monitoring-concept\monitoring-concept.md

# Custom output + per-document metadata + DRAFT watermark
development\pdf\Build-Pdf.ps1 `
-InputPath proposals\service-discovery.md `
-OutputPath dist\service-discovery.pdf `
-MetadataPath proposals\service-discovery.meta.yaml `
-Draft

Options: -OutputPath, -MetadataPath, -Draft, -NoDiagrams, -NoToc.

Per-document metadata​

The shared brand-metadata.yaml carries only the brand skin. Put per-document values in the source file's YAML front matter, or in a small metadata file passed via -MetadataPath:

title: "Platform Monitoring Concept"
subtitle: "Architecture Proposal"
author: "TOGETHER CCA · Martin Riemann"
date: "2026-07-21"

A metadata file named <document>.meta.yaml beside the source is picked up automatically — -MetadataPath is only needed to override that.

Image widths​

Pandoc's own syntax for sizing an image is an attribute block, ![alt](x.png){width=95%}. Do not use it. The same Markdown is compiled as MDX by Docusaurus, where {...} is a JavaScript expression, and the attribute block fails that build outright.

Put widths in the document's .meta.yaml instead:

image-widths:
target-architecture.png: 95%
alert-decision.png: 75%

Keys match the file name or the path as written in the document. Applied by filters/image-width.lua; an explicit attribute in the source still wins.

Diagrams​

Build-Pdf.ps1 auto-renders any *.d2 files found next to the source (and in a sibling diagrams/ folder) to PNG before the PDF build. Import brand colors in your diagrams with ...@assets/colors/_colors.d2 — see the diagram-creation skill.

Brand alignment​

  • Fonts: Roboto for body/headings (brand policy §2; installed by install.ps1). Code uses Roboto Mono, with an automatic fallback to Cascadia Mono / Consolas for glyphs Roboto Mono lacks (e.g. box-drawing characters in ASCII diagrams), so code blocks always render.
  • Colors: TOGETHER Orange #FF9900, CCA Blau #0066B2, text grey #333333 — sourced from assets/colors/colors.json.
  • Logo: Together_CCA_Logo_Farbe_RGB.png from site/static/logos/TOGETHER CCA/ (Repo-Root).

See the Brand Policy for the source of truth.

Notes & limitations​

  • Reader is pandoc markdown; Docusaurus-specific MDX/admonitions (:::note, JSX components) are not rendered — use plain Markdown for documents intended for PDF, or keep those constructs out of the PDF source.
  • Engine is LuaLaTeX (needed for fontspec / system fonts). The first build may be slow while MiKTeX fetches packages.