Zum Hauptinhalt springen

PDF Generation

🤖 Generated with Claude Code

⚠️ Not yet reviewed

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

Turn a Markdown document into a branded TOGETHER CCA PDF using the deterministic PowerShell pipeline in development/pdf/. The build MUST be driven through Build-Pdf.ps1, and pandoc/LaTeX invocations MUST NOT be hand-crafted, so that output stays consistent and on-brand.

Quick Start​

development\pdf\Build-Pdf.ps1 -InputPath <path-to-markdown.md>

The PDF is written next to the source file by default. That single call renders any *.d2 diagrams found nearby, applies the Eisvogel template, Roboto fonts, and brand colors, and produces the PDF.

Workflow (MUST — follow in order)​

  1. Confirm the source file the user wants converted (e.g. a file under proposals/, products/, or development/).
  2. Check per-document metadata. The title page needs title (and ideally subtitle, author, date). A <document>.meta.yaml beside the source is used automatically; otherwise add YAML front matter to the document or pass -MetadataPath. Example front matter:
    ---
    title: "Platform Monitoring Concept"
    subtitle: "Architecture Proposal"
    author: "TOGETHER CCA · <name>"
    date: "2026-07-21"
    ---
  3. Image widths. {width=...} attributes MUST NOT be added to images — that syntax breaks the Docusaurus build. Widths MUST go in the document's .meta.yaml instead:
    image-widths:
    target-architecture.png: 95%
  4. Ask if it's a review/internal copy — if so, add -Draft for the DRAFT watermark.
  5. Run Build-Pdf.ps1 with the chosen options.
  6. Report the output path. If the build fails on a missing tool, point the user to step "Prerequisites" below.

Options​

OptionEffect
-InputPath <md>Source Markdown (required)
-OutputPath <pdf>Output path (default: alongside source)
-MetadataPath <yaml>Per-document metadata (title/author/date/subtitle)
-DraftAdd DRAFT watermark for internal review copies
-NoDiagramsSkip D2 rendering (use existing images)
-NoTocSuppress table of contents

Prerequisites​

Requires pandoc, MiKTeX (LuaLaTeX), and d2. If a build fails because a tool is missing, run the installer, then start a new shell:

development\pdf\install.ps1

Brand alignment (already baked in)​

  • Fonts: Roboto (body) + Roboto Mono (code), with a Cascadia Mono / Consolas fallback for glyphs Roboto Mono lacks (e.g. box-drawing in ASCII diagrams).
  • Colors: TOGETHER Orange #FF9900, CCA Blau #0066B2, text grey #333333.
  • Title page: white background, orange accent rule, TOGETHER CCA logo.

Sources of truth: Brand Policy, assets/colors/colors.json (Repo-Root).

Gotchas​

  • The pandoc reader is markdown — Docusaurus MDX / admonitions (:::note, JSX components) do not render. PDF-bound documents MUST stay in plain Markdown.
  • Diagrams MUST import brand colors via ...@assets/colors/_colors.d2 (see the diagram-creation skill).
  • First build can be slow while MiKTeX auto-installs LaTeX packages.

Resources​