/publish-pdf Command

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Usage

/publish-pdf

Generate publication-grade PDFs from Markdown documents with CODITECT branding, Mermaid diagram rendering, and professional formatting. This command provides a convenient interface to the PDF generation infrastructure.

---

Syntax

/publish-pdf <input> [options]

---

Arguments

Argument	Required	Description
<input>	Yes	Path to Markdown file or directory (with --batch)

---

Options

Option	Short	Default	Description
--output	-o	pdf-output/	Output path for generated PDF
--batch		false	Process all .md files in directory
--cover		true	Include CODITECT cover page
--no-cover		false	Exclude cover page
--toc		true	Include table of contents
--no-toc		false	Exclude table of contents
--title	-t	(auto)	Override document title
--subtitle	-s	""	Add subtitle to cover
--type		technical	Document type (see below)
--check-deps			Verify dependencies

Document Types

Type	Description
technical	Technical documentation (default)
architecture	Architecture documents
user_guide	User guides and tutorials
reference	API and reference docs
internal	Internal/confidential docs

---

Examples

Basic Usage

# Generate PDF from single file
/publish-pdf docs/ARCHITECTURE.md

# Generate with custom output path
/publish-pdf docs/README.md --output ~/Desktop/readme.pdf

Cover Page Options

# With custom title and subtitle
/publish-pdf docs/API.md --title "API Reference Guide" --subtitle "Version 2.0"

# Without cover page (quick draft)
/publish-pdf docs/notes.md --no-cover

Batch Processing

# Process all markdown files in directory
/publish-pdf --batch docs/00-coditect-introduction/

# Batch with custom output directory
/publish-pdf --batch docs/architecture/ --output /tmp/arch-pdfs/

Document Classification

# Architecture document
/publish-pdf docs/system-design.md --type architecture

# Internal confidential document
/publish-pdf docs/roadmap.md --type internal

# User guide
/publish-pdf docs/getting-started.md --type user_guide

Dependency Check

# Verify all required tools are installed
/publish-pdf --check-deps

---

Output

Single File

docs/
├── my-document.md           # Source
└── pdf-output/
    └── my-document.pdf      # Generated PDF

Batch Mode

docs/00-coditect-introduction/
├── WHAT-IS-CODITECT-CORE.md
├── CODITECT-ARCHITECTURE-VISUAL.md
├── CODITECT-VISION-AND-ROADMAP.md
└── pdf-output/
    ├── WHAT-IS-CODITECT-CORE.pdf
    ├── CODITECT-ARCHITECTURE-VISUAL.pdf
    └── CODITECT-VISION-AND-ROADMAP.pdf

---

PDF Features

Branding Elements

All generated PDFs include:

• Cover Page: CODITECT logo, title, author, date, version
• Header: CODITECT branding + document title
• Footer: Copyright © 2025 AZ1.AI Inc. | Page X of Y
• Typography: Professional Inter font family
• Colors: CODITECT brand palette (#2563eb)

Diagram Support

Mermaid diagrams are automatically rendered:

• Flowcharts, sequence diagrams, class diagrams
• State diagrams, ER diagrams, Gantt charts
• Rendered at 2x scale for crisp output
• White backgrounds for print compatibility

Page Layout

Property	Value
Size	A4 (210mm × 297mm)
Margins	25mm top/bottom, 20mm sides
Orientation	Portrait

---

Dependencies

The command requires these tools:

Python (Required)

pip install md2pdf-mermaid markdown pyyaml

Node.js (Required for Mermaid)

npm install -g @mermaid-js/mermaid-cli

Alternative (Fallback)

npm install -g md-to-pdf
# OR
apt install pandoc wkhtmltopdf  # Linux
brew install pandoc wkhtmltopdf  # macOS

---

Troubleshooting

Common Issues

Issue	Solution
"Module not found"	Run pip install md2pdf-mermaid
"mmdc not found"	Run npm install -g @mermaid-js/mermaid-cli
"Diagram failed to render"	Check Mermaid syntax at mermaid.live
"Empty PDF"	Verify input file exists and is readable
"Fonts missing"	Install Inter font or use system fonts

Debug Mode

# Check all dependencies
/publish-pdf --check-deps

# Verbose output (view script directly)
python3 scripts/generate-publication-pdf.py docs/file.md

---

Implementation

This command is implemented by:

• Script: scripts/generate-publication-pdf.py
• Agent: agents/pdf-publishing-specialist.md
• Skill: skills/pdf-generation/SKILL.md
• Templates: docs/99-publishing/templates/
• Config: docs/99-publishing/config/pdf-generation-config.json

---

Expansion

When invoked, this command expands to:

Generate a publication-grade PDF document with CODITECT branding.

**Input:** {{input}}
**Options:** {{options}}

Execute the PDF generation workflow:

1. Read the source Markdown file(s)
2. Extract title and metadata from frontmatter
3. Pre-render any Mermaid diagrams to PNG images
4. Generate cover page with CODITECT branding
5. Create table of contents from headings
6. Apply CODITECT theme CSS styling
7. Generate PDF with headers, footers, and page numbers
8. Save to output directory

Use the script: `python3 scripts/generate-publication-pdf.py {{input}} {{options}}`

Report the generated PDF location(s) and file size(s).

---

Related Commands

Command	Purpose
/fix-mermaid-diagrams	Fix Mermaid syntax for GitHub
/documentation-librarian	Organize documentation
/export-dedup	Export session for documentation

---

Version History

Version	Date	Changes
1.0.0	2025-12-16	Initial release

---

Success Output

When PDF generation completes:

✅ COMMAND COMPLETE: /publish-pdf
Input: <source-file.md>
Output: <output-path.pdf>
Pages: N
File Size: X KB
Diagrams: N rendered
Status: Generated successfully

Completion Checklist

Before marking complete:

• Input file validated
• Mermaid diagrams rendered
• Cover page generated (if enabled)
• Table of contents built
• PDF written to output
• File size reported

Failure Indicators

This command has FAILED if:

• ❌ Input file not found
• ❌ Mermaid rendering errors
• ❌ No PDF generated
• ❌ Missing dependencies

When NOT to Use

Do NOT use when:

• Quick preview needed (use markdown viewer)
• File already is PDF
• Dependencies not installed

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip dependency check	Runtime errors	Run --check-deps first
Large batch without output dir	Clutter	Use --output option
No cover for formal docs	Unprofessional	Keep --cover default

Principles

This command embodies:

• #3 Complete Execution - Full PDF pipeline
• #6 Clear, Understandable - Professional output

Full Standard: 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