pdf-export

name	pdf-export
description	Produces a typeset PDF artifact from any source file — code, Markdown, HTML, chat JSON, or structured Dojo files (specs, ADRs, skills). Use when: "export this to PDF", "generate a PDF of this file", "make a PDF from this".

PDF Export Skill

Version: 0.1.1 Created: 2026-04-08 Author: Dojo Genesis Purpose: Convert any file into a beautifully typeset PDF using Pretext's Canvas-based typography engine for precise text measurement and layout.

---

I. The Philosophy: Typography as Respect

A PDF is a permanent artifact. Unlike a terminal dump or a browser render, a PDF says "this was worth preserving." Pretext-powered export treats every character with the same care a typesetter would — measuring widths on a real Canvas, computing line breaks honestly, and placing glyphs with sub-pixel precision. The result: PDFs that are not just functional, but beautiful.

---

II. When to Use This Skill

• Code review artifacts: Export source files with syntax highlighting for offline review or archival.
• Documentation publishing: Convert Markdown specs, ADRs, or READMEs into distributable PDFs.
• Chat preservation: Export DojoChat conversations with faithful typography and bubble layout.
• Structured file bundles: Batch-export SKILL.md files, handoff packages, or decision records.
• HTML snapshots: Render HTML pages to PDF preserving layout and styles.

---

III. Steps

Step 1: Identify Source Files

Determine the files to export and their types. Supported formats:

Format	Renderer	Features
.ts, .js, .go, .py, .rs, etc.	Code	Syntax highlighting via Shiki, line numbers, theme support
.md	Markdown	Heading hierarchy, code blocks, tables, links as footnotes
.html	HTML	DOM-faithful rendering, CSS preservation
Chat JSON	Chat	Bubble layout, Pretext shrink-wrap, disposition typography
SKILL.md, ADR-*.md	Structured	Section-aware layout, metadata headers, cross-references

Step 2: Configure Typography

Choose typography settings or accept defaults:

• Font stack: Inter (body), Recursive (code), Fraunces (display)
• Body size: 11pt (default), configurable 8-16pt
• Line height: 1.5 (default), configurable 1.2-2.0
• Page size: Letter (default), A4, Legal
• Margins: 72pt (1 inch) all sides (default)

Step 3: Invoke the Export

Use the MCP tool pretext-pdf.export or the slash command:

/export-pdf path/to/file.md --output ./exports/
/export-pdf src/**/*.ts --output ./code-review.pdf --bundle
/export-pdf chat-export.json --theme dark

Step 4: Verify Output

Check the generated PDF for:

• Text renders correctly (no tofu/missing glyphs)
• Code blocks preserve indentation and highlighting
• Page breaks fall at logical boundaries
• Headers and footers appear consistently

Step 5: Deliver

The PDF is written to the specified output path. Share it, archive it, or upload it via a file storage connector.

---

IV. Quality Checklist

Before delivering an exported PDF, verify:

• Source file format was correctly identified (not guessed) — wrong renderer produces broken layout
• Typography settings were tuned for the content type (code vs. prose vs. chat), not left at defaults
• Output path exists or was created; the file is non-zero bytes
• Page breaks fall at logical boundaries, not mid-sentence or mid-function
• Code blocks preserve indentation and do not overflow margins
• Headers and footers appear on every page consistently
• No missing glyphs (tofu rectangles) in the rendered text
• Multi-file bundles have a coherent narrative — unrelated files are not mixed into one PDF
• Sensitive content was flagged to the user before creating a permanent artifact
• File size is within expected range for the content type (prose ~30-80 KB/page, code ~15-40 KB/page)

---

V. Reflection Questions

• Is the source file format correctly detected, or does it need a format hint?
• Are the typography defaults appropriate for this content, or should they be tuned?
• Should multiple files be bundled into a single PDF or exported individually?
• Does the content contain sensitive information that should not be in a permanent artifact?

---

VI. Common Mistakes

• Exporting without reading the file first. Always read the source to understand its structure before choosing renderer settings.
• Using default typography for code-heavy files. Code benefits from a smaller font (9-10pt) and tighter line height (1.3) than prose.
• Ignoring page breaks. Long files need explicit section breaks. The Markdown renderer auto-breaks at ## headings; code breaks every 60 lines.
• Bundling unrelated files. A single PDF should have a coherent narrative. Don't bundle a README with unrelated test files.
• Forgetting dark theme for code. Syntax highlighting on white backgrounds can wash out. Use --theme dark for code-centric exports.

---

VII. Variations

Minimal Export

Single file, default settings, quick output:

/export-pdf README.md

Code Review Bundle

Multiple source files with dark theme and line numbers:

/export-pdf src/lib/**/*.ts --bundle --theme dark --line-numbers

Chat Archive

DojoChat conversation with Pretext typography:

/export-pdf conversation.json --renderer chat --disposition-typography

Structured Ecosystem Export

All skills in a plugin as a reference manual:

/export-pdf plugins/agent-orchestration/skills/*/SKILL.md --bundle --toc

---

VIII. Example

Scenario: Export the handoff protocol skill as a distributable PDF for a new team member.

1. Read the source: plugins/agent-orchestration/skills/handoff-protocol/SKILL.md
2. Detect format: Structured Markdown (has YAML frontmatter + numbered sections)
3. Apply structured renderer with defaults: Inter 11pt, 1.5 line height, Letter
4. Generate table of contents from ## headings
5. Render code blocks in Recursive with Shiki highlighting
6. Output: exports/handoff-protocol.pdf (12 pages, 45KB)

---

IX. See Also

• pdf-typography — Fine-tune Pretext typography settings for specific content types
• handoff-protocol (agent-orchestration) — Export handoff packages as PDFs
• specification-writer (specification-driven-development) — Generate specs then export as PDF
• status-writing (system-health) — Export STATUS.md as formatted PDF reports

---

Output

• A .pdf file written to the specified --output path (default: ./exports/<source-basename>.pdf)
• When bundling multiple files: a single merged PDF with an auto-generated table of contents
• File size varies by content: prose ~30-80 KB/page, code ~15-40 KB/page

Examples

Scenario 1: "Export this ADR as a PDF for the client" → reads ADR-007.md, applies structured renderer with Inter 11pt, generates exports/ADR-007.pdf with section headings and a ToC.

Scenario 2: "Make a PDF of all the TypeScript source files in src/lib" → bundles src/lib/**/*.ts with dark theme, syntax highlighting, line numbers; outputs exports/src-lib-bundle.pdf.

Edge Cases

• Source file contains binary data or is not text-decodable: report the issue and skip that file; do not silently produce a corrupted PDF.
• Glob pattern matches zero files: stop and inform the user before attempting export.
• Output path directory does not exist: create intermediate directories rather than failing silently.
• File exceeds 10,000 lines: warn the user about page count before proceeding; offer to split by section.

Anti-Patterns

• Exporting without reading the source first — choosing the wrong renderer (e.g., Markdown renderer for a raw HTML file) produces broken layout.
• Bundling files from different projects or contexts into a single PDF — the result lacks coherence and confuses readers.
• Using default 11pt body size for code-heavy files — code at 11pt overflows narrow margins; use 9-10pt for code-primary exports.
• Skipping the verify step (Step 4) — orphaned headings, overflowing code blocks, and tofu characters only surface at review time, not during rendering.