PDF Generation Skill

When to Use This Skill

Use this skill when implementing pdf generation patterns in your codebase.

How to Use This Skill

Review the patterns and examples below
Apply the relevant patterns to your implementation
Follow the best practices outlined in this skill

The PDF Generation skill provides publication-grade document conversion capabilities for the CODITECT framework. It transforms Markdown documentation into professionally formatted PDFs with consistent branding, Mermaid diagram rendering, and enterprise-quality output.

Skill Definition

name: pdf-generation
description: Generate publication-grade PDFs from Markdown with Mermaid diagrams, CODITECT branding, and professional formatting
category: documentation
version: 1.0.0
author: Hal Casteel, Founder/CEO/CTO
copyright: 2025 AZ1.AI Inc.

capabilities:
  - markdown_to_pdf
  - mermaid_rendering
  - cover_page_generation
  - toc_generation
  - batch_processing
  - consistent_branding

dependencies:
  python:
    - md2pdf-mermaid
    - markdown
    - pyyaml
  npm:
    - "@mermaid-js/mermaid-cli"
    - md-to-pdf

triggers:
  - pattern: "generate.*pdf"
  - pattern: "publish.*document"
  - pattern: "convert.*markdown.*pdf"
  - pattern: "create.*publication"

Usage Patterns

Pattern 1: Single Document Conversion

# Using the script directly
python3 scripts/generate-publication-pdf.py docs/architecture.md

# With options
python3 scripts/generate-publication-pdf.py docs/README.md --cover --toc --title "User Guide"

Pattern 2: Batch Processing

# Convert all markdown in a directory
python3 scripts/generate-publication-pdf.py --batch docs/00-coditect-introduction/

# With custom output directory
python3 scripts/generate-publication-pdf.py --batch docs/architecture/ --output /tmp/pdfs/

Pattern 3: Via Slash Command

# In Claude Code session
/publish-pdf docs/WHAT-IS-CODITECT-CORE.md

# Batch mode
/publish-pdf --batch docs/00-coditect-introduction/

Pattern 4: Via Agent

Task(
    subagent_type="pdf-publishing-specialist",
    prompt="Generate publication PDF for the architecture documentation"
)

Templates & Configuration

Directory Structure

docs/99-publishing/
├── templates/
│   ├── header.html           # Page header template
│   ├── footer.html           # Page footer with page numbers
│   ├── cover-page.html       # Cover page template
│   └── coditect-theme.css    # CODITECT brand styling
└── config/
    └── pdf-generation-config.json  # Default settings

CSS Theme Features

The CODITECT theme (coditect-theme.css) provides:

Typography: Inter font family, optimized line heights
Colors: CODITECT brand palette (#2563eb primary)
Code Blocks: Syntax highlighting with dark theme
Tables: Striped rows, branded headers
Callouts: Info, warning, error, success styles
Print Optimization: Page break controls, color accuracy

Configuration Options

{
  "defaults": {
    "page_size": "A4",
    "include_cover": true,
    "include_toc": true,
    "page_numbers": true
  },
  "branding": {
    "organization": "AZ1.AI Inc.",
    "author": "Hal Casteel, Founder/CEO/CTO",
    "copyright_year": 2025
  },
  "mermaid": {
    "enabled": true,
    "theme": "default",
    "output_format": "png",
    "scale": 2
  }
}

Output Specifications

Page Layout

Property	Value
Page Size	A4 (210mm × 297mm)
Top Margin	25mm
Bottom Margin	25mm
Left Margin	20mm
Right Margin	20mm

Branding Elements

Element	Content
Header	CODITECT logo + Document title
Footer	Copyright © 2025 AZ1.AI Inc. \| Author \| Page X of Y
Cover	Logo, title, author, date, version, classification

Quality Metrics

Metric	Target
Image Resolution	2x scale (retina)
Font Embedding	Full
PDF Version	1.7
Compression	Enabled

Mermaid Diagram Support

Supported Diagram Types

Flowcharts (graph TD, graph LR)
Sequence Diagrams (sequenceDiagram)
Class Diagrams (classDiagram)
State Diagrams (stateDiagram-v2)
Entity Relationship (erDiagram)
Gantt Charts (gantt)
Pie Charts (pie)
Git Graphs (gitGraph)

Rendering Pipeline

Extract Mermaid code blocks from Markdown
Write each diagram to temporary .mmd file
Render via mermaid-cli to PNG (2x scale)
Replace code block with image reference
Include rendered image in final PDF

Example

Source Markdown:

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

Rendered Output:

PNG image at 2x resolution
Embedded in PDF at original size
White background for print compatibility

Error Handling

Dependency Checks

# Verify all dependencies
python3 scripts/generate-publication-pdf.py --check-deps

Common Errors

Error	Solution
`ModuleNotFoundError: md2pdf_mermaid`	`pip install md2pdf-mermaid`
`mmdc: command not found`	`npm install -g @mermaid-js/mermaid-cli`
`Parse error in mermaid diagram`	Validate at mermaid.live
`PDF output empty`	Check input file path and permissions

Fallback Chain

The skill attempts PDF generation in this order:

md2pdf-mermaid (Python, preferred)
md-to-pdf (npm/npx)
Pandoc + wkhtmltopdf (fallback)

Integration Points

Component	Type	Description
`pdf-publishing-specialist`	Agent	Autonomous PDF publishing agent
`/publish-pdf`	Command	Slash command for PDF generation
`generate-publication-pdf.py`	Script	Core generation script
`docs/99-publishing/`	Templates	Branding and configuration

Workflow Integration

# In multi-step workflow
steps = [
    "Edit documentation",
    "Run /publish-pdf to generate PDFs",
    "Review generated PDFs",
    "Commit and distribute"
]

Best Practices

Content Preparation

Use clear heading hierarchy (H1 → H2 → H3)
Validate Mermaid syntax before generation
Include frontmatter with title and metadata
Keep tables simple for better rendering
Use relative paths for images

Performance

Batch similar documents together
Pre-render complex diagrams if reusing
Cache generated PDFs for unchanged content
Use --no-cover for quick drafts

Quality Assurance

Check all diagrams rendered correctly
Verify page breaks are appropriate
Review table formatting in output
Validate hyperlinks work in PDF
Test print output matches screen

Version History

Version	Date	Changes
1.0.0	2025-12-16	Initial skill definition

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: pdf-generation

Completed:
- [x] PDF generated with publication-grade quality
- [x] Mermaid diagrams rendered correctly
- [x] CODITECT branding applied (cover, header, footer)
- [x] Table of contents generated
- [x] All images embedded correctly

Outputs:
- path/to/document.pdf (publication-ready)
- path/to/document-cover.html (if --cover used)
- /tmp/mermaid-diagrams/*.png (rendered diagrams)
- PDF metadata (author, title, copyright)

Completion Checklist

Before marking this skill as complete, verify:

Failure Indicators

This skill has FAILED if:

❌ PDF file not created or empty
❌ Mermaid diagrams missing or showing as code blocks
❌ Cover page template not found or incorrect
❌ Table of contents broken or missing
❌ Page breaks in wrong locations
❌ Images missing or broken in PDF
❌ CODITECT branding incomplete (missing logo/copyright)
❌ Syntax errors in Mermaid diagrams
❌ Dependencies missing (md2pdf-mermaid, mmdc)
❌ PDF file size exceeds 50MB

When NOT to Use

Do NOT use this skill when:

Need HTML output only (use markdown rendering instead)
Converting simple text files (use basic PDF converters)
Need editable output (use DOCX conversion)
Creating forms or fillable PDFs (use form-specific tools)
Generating reports with dynamic data (use report-generation skill)
Need LaTeX-quality academic papers (use LaTeX workflow)
Creating slideshows/presentations (use presentation tools)

Use alternative skills:

markdown-to-html - Web-friendly HTML output
report-generation - Dynamic data-driven reports
latex-workflow - Academic paper formatting
documentation-publishing - Multi-format documentation sites

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
No dependency check	PDF generation fails silently	Run `--check-deps` before batch processing
Complex Mermaid diagrams	Rendering failures or unreadable output	Test at mermaid.live, simplify if needed
Missing frontmatter	No metadata in cover page	Add YAML frontmatter to source markdown
Large embedded images	Huge PDF file sizes	Optimize images before conversion
Relative image paths	Broken images in PDF	Use absolute paths or place images in same dir
No print testing	Output doesn't match expectations	Always review print preview before distribution
Batch without verification	Silent failures unnoticed	Check each PDF after batch processing
Missing CSS theme	Inconsistent branding	Always use CODITECT theme or custom CSS

Principles

This skill embodies these CODITECT principles:

#2 First Principles - Understanding PDF rendering pipeline (Markdown → HTML → PDF)
#3 Keep It Simple - Single command generates publication-ready output
#4 Self-Provisioning - Auto-install dependencies, create templates
#6 Clear, Understandable, Explainable - Professional formatting communicates authority
#7 Inform, Don't Ask - Automatic fallback chain for PDF generation
#10 Complete Execution - Full pipeline from source to branded PDF

Full Principles: CODITECT-STANDARD-AUTOMATION.md

Owner: AZ1.AI Inc. Lead: Hal Casteel, Founder/CEO/CTO Framework Version: CODITECT v1.7.2 Last Updated: December 16, 2025

When to Use This Skill​

How to Use This Skill​

Skill Definition​

Usage Patterns​

Pattern 1: Single Document Conversion​

Pattern 2: Batch Processing​

Pattern 3: Via Slash Command​

Pattern 4: Via Agent​

Templates & Configuration​

Directory Structure​

CSS Theme Features​

Configuration Options​

Output Specifications​

Page Layout​

Branding Elements​

Quality Metrics​

Mermaid Diagram Support​

Supported Diagram Types​

Rendering Pipeline​

Example​

Error Handling​

Dependency Checks​

Common Errors​

Fallback Chain​

Integration Points​

Related Components​

Workflow Integration​

Best Practices​

Content Preparation​

Performance​

Quality Assurance​

Version History​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​