ZigPDF

Ultra-fast PDF generation framework written in Zig

Generate PDFs in 1-8ms with declarative templates. Production-ready, language-agnostic CLI that works with any programming language.

---

🚀 Quick Start

New to ZigPDF? → QUICKSTART.md - Get started in 5 minutes

Build & Run:

zig build
./zig-out/bin/zigpdf --help

Generate your first PDF:

# Create template
cat > invoice.pdm <<'EOF'
#page(width: 595, height: 842, margin: 50)
#font(helvetica-bold, helvetica)
#text("{{title}}", font: 0, size: 18, margin-bottom: 10)
#text("Date: {{date}}", font: 1, size: 12)
EOF

# Compile template
./zig-out/bin/zigpdf --markup-to-template invoice.pdm invoice.bin

# Generate PDF
echo '{"fields":{"title":"Invoice #001","date":"2024-10-10"}}' | \
  ./zig-out/bin/zigpdf --generate-pdf invoice.bin - output.pdf

🎉 Done! PDF created in ~1ms

---

✨ Key Features

⚡ Blazing Fast

• 1.65ms per PDF (simple documents)
• 4.5ms per PDF (500 rows, 18 pages)
• 607 PDFs/second throughput
• 134x faster than spawning separate processes
• Zero-copy operations, memory leak-free

🎯 Easy to Use

• Automatic layout - no manual x,y coordinates needed
• Declarative templates - clean PDM markup language
• Binary templates - precompiled for maximum speed
• Dynamic fields - {{variable}} substitution
• Tables with auto-pagination - automatic page breaks

🔧 Language Agnostic

Works with any programming language via simple CLI:

• Go, Python, Node.js, Rust, Shell, PHP, Ruby, etc.
• No library bindings required
• JSON in, PDF out

🎨 Production Ready

• ✅ Valid PDF 1.4 output
• ✅ Conditional rendering (#if/#else blocks)
• ✅ Headers & footers with repeat modes
• ✅ Image support (PNG with transparency)
• ✅ Built-in standard fonts
• ✅ Comprehensive error handling

---

📖 Documentation

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• PDM Tutorial - Complete syntax guide (1,100+ lines)
• Template Examples - 8 ready-to-use templates

Features & Guides

• Layout System - Automatic and absolute positioning
• Conditional Rendering - Dynamic content with #if/#else

Performance & Benchmarks

• Benchmark Results - Comprehensive performance analysis
• Conditional Rendering Performance - <0.1ms overhead per condition
• Text Wrapping Performance - Sub-millisecond text flow
• TrueType Font Performance - Font loading benchmarks

Implementation Details

• Conditional Blocks Implementation - How conditionals work
• Text Wrapping Implementation - Text flow algorithms
• Parser Roadmap - Future enhancements

Full documentation index: docs/README.md

---

⚡ Performance

Benchmarks

Method	100 PDFs	Per PDF	Throughput	Use Case
Process-per-PDF	22,000ms	220ms	4.5/sec	Scripts
Batch Mode	165ms	1.65ms	607/sec	Production
Speedup	134x	134x	134x

Real-World Performance

=== Simple Documents ===
Batch Mode (100 PDFs): 165ms
Average per PDF: 1.65ms
Throughput: 607 PDFs/sec

=== Large Tables (500 rows) ===
Per PDF: 4.5ms
Throughput: 220 PDFs/sec

---

🌐 Language Integration

Single PDF Mode

echo '{"fields":{"title":"My Doc"}}' | zigpdf --generate-pdf template.bin - output.pdf

Batch Mode (Recommended)

# Generate NDJSON (one JSON per line)
cat > batch.ndjson <<'EOF'
{"data":{"fields":{"title":"Report 1"}},"output":"report1.pdf"}
{"data":{"fields":{"title":"Report 2"}},"output":"report2.pdf"}
EOF

# Process all PDFs in one process
zigpdf --batch-mode template.bin < batch.ndjson

Integration Examples

Python:

import json
import subprocess

proc = subprocess.Popen(['zigpdf', '--batch-mode', 'template.bin'],
                       stdin=subprocess.PIPE, text=True)
for i in range(100):
    req = {"data": {"fields": {"title": f"Doc {i}"}}, "output": f"doc{i}.pdf"}
    proc.stdin.write(json.dumps(req) + '\n')
proc.stdin.close()
proc.wait()

Go:

cmd := exec.Command("zigpdf", "--batch-mode", "template.bin")
stdin, _ := cmd.StdinPipe()
cmd.Start()

encoder := json.NewEncoder(stdin)
for _, req := range requests {
    encoder.Encode(req)
}

stdin.Close()
cmd.Wait()

Node.js:

const zigpdf = spawn('zigpdf', ['--batch-mode', 'template.bin']);
for (const req of requests) {
    zigpdf.stdin.write(JSON.stringify(req) + '\n');
}
zigpdf.stdin.end();

---

📋 Template Markup (PDM)

Automatic Layout

#page(width: 595, height: 842, margin: 40)
#font(helvetica-bold, helvetica)

# Elements flow top-to-bottom automatically
#text("{{title}}", font: 0, size: 18, margin-bottom: 10)
#text("{{subtitle}}", font: 1, size: 12, margin-bottom: 20)
#line(width: 1.5, margin-bottom: 15)
#text("Total: ${{amount}}", font: 0, size: 16)

Conditional Rendering

#if(payment_status == "paid") {
  #text("✓ PAID", x: 350, y: 645, font: 0, size: 11)
} else {
  #text("⚠ OVERDUE", x: 350, y: 645, font: 0, size: 11)
}

#if(invoice_total > "10000") {
  #text("⭐ PRIORITY ACCOUNT", x: 40, y: 384, font: 0, size: 9)
}

Operators: ==, !=, >, <, >=, <= Performance: <0.03ms per condition

Tables with Auto-Pagination

#table(
  data: "items",
  x: 50, y: 700,
  columns: [
    (width: 200, align: left),
    (width: 100, align: right)
  ],
  headers: ["Description", "Amount"],
  font: 1, size: 10
)

Tables automatically split across pages!

---

🏗️ Architecture

zig/
├── src/
│   ├── pdf/
│   │   ├── writer.zig       # PDF 1.4 object generation
│   │   ├── content.zig      # Drawing primitives
│   │   ├── font.zig         # Font handling
│   │   ├── paginate.zig     # Table pagination
│   │   └── template.zig     # Binary template format
│   └── pdf_lib.zig          # Main library entry
├── docs/
│   ├── tutorial/            # PDM syntax tutorials
│   ├── features/            # Feature documentation
│   ├── performance/         # Benchmark reports
│   └── implementation/      # Technical details
├── examples/                # Usage examples
└── templates/               # Binary templates

Binary Template Format

Magic: TPDF (0x54504446)
Version: 1
Page Config: width, height, margins
Fonts: [font_type, ...]
Fields: [key, x, y, font_index, size, ...]
Tables: columns, headers, style
Static Content: precompiled PDF streams

Benefits: Fast loading (~0.1ms), reusable, versioned, compact (1-10KB)

---

🔧 Building

Development

zig build

Production (2-3x faster)

zig build -Doptimize=ReleaseFast

Available Targets

zig build run          # Single PDF example
zig build gen1000      # 1000 PDFs benchmark
zig build template     # Template builder

---

📊 CLI Reference

# Compile template
zigpdf --markup-to-template <input.pdm> <output.bin>

# Generate single PDF
zigpdf --generate-pdf <template.bin> <data.json|-> <output.pdf>

# Batch mode (fastest)
zigpdf --batch-mode <template.bin> < input.ndjson

# Help
zigpdf --help

JSON Input Format

IMPORTANT: Fields must be nested under "fields" key!

✅ Correct:

{
  "fields": {
    "title": "Invoice #001",
    "date": "2024-10-10",
    "items": [
      ["Item", "Price"],
      ["Service", "$100"]
    ]
  }
}

❌ Wrong (will create blank PDF):

{
  "title": "Invoice #001",
  "date": "2024-10-10"
}

---

🗺️ Roadmap

Current (v1.3)

• ✅ PDF 1.4 generation
• ✅ Automatic layout with margin control
• ✅ Conditional rendering (#if/#else)
• ✅ Table auto-pagination
• ✅ Headers & footers with repeat modes
• ✅ Image support (PNG)
• ✅ Batch mode (1.65ms per PDF)
• ✅ Memory leak-free
• ✅ Language-agnostic CLI

Future

Content stream compression (~40% size reduction)
TrueType/OpenType fonts
Additional image formats (JPEG, WebP)
PDF/A compliance
Digital signatures
Parallel batch mode
Visual template editor

---

📄 License

ZigPDF Non-Commercial License

• ✅ Free use for personal, educational, internal business
• ✅ Modify, distribute, use in your applications
• ❌ Cannot sell ZigPDF itself as a product
• ❌ Cannot offer as SaaS to others

See LICENSE for complete terms.

---

📞 Support

• Issues: File issues on GitHub
• Documentation: docs/README.md
• Quick Start: QUICKSTART.md
• Context: PROJECT_CONTEXT.md

---

🙏 Acknowledgments

Built with Zig - a general-purpose programming language for maintaining robust, optimal, and reusable software.

Why Zig?

• Memory safety without garbage collection
• Compile-time execution
• Zero-cost abstractions
• Excellent performance

---

Made with ⚡ by the ZigPDF Team