/latex

PURPOSE

Orchestrate full LaTeX PDF generation: load data from JSON, a markdown file, or a collection of markdown files — extract Mermaid/Graphviz diagram blocks, generate PNGs via capability:diagram:generate, then compile the PDF via capability:latex:write.

EXECUTION

1. Resolve Data Source

   Detect the --data input type and load template variables:

   --data value	Type	Action
   Starts with {	JSON string	Parse directly as template variables
   Path to a .md file	Markdown file	Read file → extract variables and diagram blocks
   Path to a directory	Collection	Read all .md files → merge content into template variables
   Omitted	None	Use empty data, rely on template defaults

2. Extract from Markdown (when --data is a file or directory)

   • Parse front matter (YAML between --- delimiters) as template variables
   • Extract named diagram blocks — fenced code blocks tagged with a diagram key (optionally with explicit renderer):

     ```mermaid diagram_sequence
     sequenceDiagram
       Client->>API: POST /order
     ```
     
     ```d2 diagram_arch
     direction: down
     wasm -> bff: GraphQL
     ```
     
     ```python diagram_infra
     from diagrams import Diagram
     from diagrams.azure.compute import AppService
     ...
     ```
     

   • Extract unnamed diagram blocks — indexed as diagram_1, diagram_2, etc.; renderer auto-selected per diagram content
   • Map section headings to template fields — e.g. ## Overview → overview, ## Core Responsibilities → core_responsibilities
   • For collections (directory): merge all files — later files override earlier ones for the same key; diagrams indexed by filename prefix + block index

3. Generate Diagrams

   For each diagram_* key whose value is diagram source code:

   • Select the best renderer using the table below
   • Invoke capability:diagram:generate with renderer type in parallel
   • Replace value with generated PNG path
   • Save PNGs to --diagrams-dir (default: <output_dir>/diagrams/)

   Renderer selection — apply the first matching rule:

   Condition	Renderer	Rationale
   Value ends with .png, .svg, .pdf or starts with /, ./, ~/	(skip — already a path)	Pre-existing image
   Tagged with explicit renderer hint (e.g. ```d2 diagram_arch)	use tagged renderer	User override — highest priority
   Starts with @startuml	plantuml	PlantUML-specific syntax
   Starts with digraph, graph {, strict digraph	graphviz	Graphviz DOT syntax
   Starts with sequenceDiagram, stateDiagram, gantt, journey, gitgraph, timeline	mermaid	Types unsupported by diagrams package
   All other diagram code (C4, flowchart, graph, erDiagram, mindmap, architecture, or any Python diagrams code)	diagrams ⬅ default	Default renderer — Python diagrams package with C4 support and cloud icons

4. Compile PDF

   Invoke capability:latex:write with resolved data (all diagram_* keys now contain PNG paths).

5. Report

   Confirm PDF path, list diagrams generated, report any skipped placeholders.

DELEGATION

• capability:diagram:generate — Render diagram code to PNG (parallel for multiple diagrams)
• capability:latex:write — Compile LaTeX template to PDF

WORKFLOW

sequenceDiagram
    participant U as User
    participant B as behavior:document:latex
    participant D as capability:diagram:generate
    participant L as capability:latex:write

    U->>B: --template --output --data
    B->>B: Detect data type (JSON / .md file / directory)
    alt Markdown file or collection
        B->>B: Parse front matter + extract diagram blocks + map sections
    end
    par Generate diagrams (parallel)
        B->>D: diagram_* code → PNG
    end
    D-->>B: PNG paths
    B->>B: Replace diagram codes with PNG paths
    B->>L: --template --output --data (resolved)
    L-->>B: PDF compiled
    B-->>U: PDF ready + diagrams listed

EXAMPLES

# From JSON data
/behavior:document:latex \
  --template architecture-overview \
  --output ./docs/architecture.pdf \
  --data '{"project_name":"MySystem","diagram_context":"C4Context\n  Person(u,\"User\")\n  System(s,\"System\")\n  Rel(u,s,\"Uses\")"}'

# From a single markdown file (front matter + mermaid blocks extracted)
/behavior:document:latex \
  --template service-architecture \
  --output ./docs/service.pdf \
  --data ./docs/service-architecture.md

# From a collection directory (all .md files merged)
/behavior:document:latex \
  --template architecture-overview \
  --output ./docs/full-architecture.pdf \
  --data ./docs/architecture/

# With pre-existing diagram images
/behavior:document:latex \
  --template service-data-model \
  --output ./docs/model.pdf \
  --data '{"service_name":"Payment","diagram_er":"./diagrams/er.png"}'

Markdown File Format

---
service_name: OrderService
author: Team
date: 2026-03-26
---

## Overview
Brief service description here.

## Core Responsibilities
Handles order lifecycle management.

```mermaid diagram_container
C4Container
  Container(api, "API", "ASP.NET")
  Container(db, "DB", "PostgreSQL")
  Rel(api, db, "Reads")

sequenceDiagram
  Client->>API: POST /order
  API->>DB: Insert
  DB-->>API: OK
  API-->>Client: 201

## OUTPUT

- PDF file at `--output` path
- List of diagrams generated (name → PNG path)
- Skipped placeholders (diagram_* keys without code or path)
- Compilation status