# 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*