ralph-vibe/examples/sample-PROMPT.md

Project: md2pdf

Objective

CLI tool that converts markdown files to beautifully styled PDF documents with syntax highlighting for code blocks, multiple theme support, and optional table of contents.

---

Application Type

CLI tool

Architecture

• Interface types: CLI arguments
• Persistence: None (stateless transformation)
• Deployment: Package registry (npm) + standalone binary

Tech Stack

• Language: TypeScript
• Runtime: Node.js 20+
• CLI: Commander.js
• PDF Generation: puppeteer + marked
• Syntax Highlighting: shiki
• Testing: Vitest
• Build: tsup

---

User Flow

┌─────────────────────────────────────────────────────────────────────┐
│                         USER JOURNEY                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  1. BASIC USAGE                                                     │
│     $ md2pdf input.md                                               │
│     → Converts input.md to input.pdf                                │
│                                                                      │
│  2. WITH OPTIONS                                                    │
│     $ md2pdf input.md -o output.pdf --theme dark --toc             │
│     → Converts with dark theme and table of contents                │
│                                                                      │
│  3. MULTIPLE FILES                                                  │
│     $ md2pdf *.md -o combined.pdf                                   │
│     → Combines all markdown files into one PDF                      │
│                                                                      │
│  4. STDIN                                                           │
│     $ cat README.md | md2pdf -o readme.pdf                         │
│     → Reads from stdin                                              │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

---

Commands

md2pdf <input> [options]

Convert markdown to PDF.

Options:
  -o, --output <path>     Output PDF path (default: input with .pdf extension)
  -t, --theme <name>      Theme: light, dark, custom (default: light)
  --toc                   Include table of contents
  --no-highlight          Disable syntax highlighting
  --page-size <size>      Page size: A4, Letter, Legal (default: A4)
  --margin <size>         Page margins in mm (default: 20)

---

Core Features

Feature 1: Basic Conversion

Description: Convert a single markdown file to PDF.

Acceptance Criteria:

• md2pdf input.md creates input.pdf
• Output is valid PDF that opens in all readers
• Markdown headings render as styled headings
• Links are clickable in PDF
• Images are embedded

Feature 2: Syntax Highlighting

Description: Code blocks render with syntax highlighting.

Acceptance Criteria:

• Code blocks with language tags are highlighted
• Supports at least: js, ts, python, rust, go, bash
• Colors appropriate to selected theme
• Monospace font for code
• Line numbers optional

Feature 3: Theme Support

Description: Multiple visual themes for output.

Acceptance Criteria:

• --theme light uses light background with dark text
• --theme dark uses dark background with light text
• Custom CSS can be loaded via --theme path/to/custom.css
• Theme affects both prose and code blocks

Feature 4: Table of Contents

Description: Generate TOC from headings.

Acceptance Criteria:

• --toc flag adds TOC at beginning
• TOC entries are clickable links
• Supports heading levels 1-3
• Page numbers shown

Feature 5: GitHub Flavored Markdown

Description: Support GFM extensions.

Acceptance Criteria:

• Tables render correctly
• Task lists render with checkboxes
• Strikethrough text renders
• Autolinks work

---

Completion Criteria

1. npm run build exits 0
2. npm run test exits 0 with >80% coverage
3. npm run lint exits 0
4. md2pdf --help shows all options
5. md2pdf README.md produces valid PDF
6. md2pdf test.md --theme dark uses dark theme
7. Code blocks show syntax highlighting
8. md2pdf test.md --toc includes table of contents
9. GFM tables render correctly

Output <promise>PROJECT_COMPLETE</promise> when all criteria met.

---

Phase 1: Foundation

• Project setup with TypeScript, tsup, vitest
• CLI framework with Commander.js
• Basic markdown parsing with marked
• PDF generation with puppeteer

Acceptance: md2pdf input.md produces basic PDF

Phase 2: Styling

• Light theme CSS
• Dark theme CSS
• Custom theme loading
• Syntax highlighting with shiki

Acceptance: md2pdf test.md --theme dark works with highlighting

Phase 3: Features

• Table of contents generation
• GFM support (tables, task lists)
• Multiple file handling
• Stdin support

Acceptance: All features work, tests pass

Phase 4: Polish

• Error handling and messages
• Documentation
• npm packaging

Acceptance: All completion criteria met

---

PRD Version: 1.0 Target: Claude Code + Ralph Method