# md-to-docx

## Purpose

Convert a Markdown file to a professionally styled Word document (.docx) suitable for sharing with non-technical stakeholders (managers, C-levels, partners).

## Dependencies

- `pandoc` (3.x+) — Markdown to docx conversion
- `python3` with `python-docx` package — post-processing and styling

## Usage

```
md-to-docx [OPTIONS] <input.md>
```

### Arguments

| Argument | Description |
|---|---|
| `<input.md>` | Path to the Markdown file to convert (required) |

### Options

| Flag | Description |
|---|---|
| `--output`, `-o` | Output file path (default: same name as input with `.docx` extension) |
| `--title`, `-t` | Override document title (default: first `# heading` in the markdown) |
| `--toc` | Include a table of contents (default: off) |
| `--toc-depth` | TOC depth level, 1-3 (default: 2, only applies when `--toc` is set) |
| `--dryrun`, `-n` | Preview what would happen without creating files |
| `--help`, `-h` | Show usage information |

## Behaviour

1. **Validate inputs.** Check that `<input.md>` exists and is readable. Check that `pandoc` is on PATH. Check that `python-docx` is importable. Exit 1 with a clear message if any check fails.

2. **Extract title.** If `--title` is not provided, scan the markdown for the first `# heading` and use its text as the document title. If no heading found, use the filename (without extension).

3. **Create styled reference doc.** Generate a temporary pandoc reference.docx and apply professional styling:
   - Font: Calibri throughout
   - Headings: navy (#1A1A2E) for H1, professional blue (#1B4D89) for H2/H3
   - Body: dark grey (#333333), 11pt, 16pt line spacing
   - Comfortable margins (2.5cm all sides)
   - Hyperlinks: blue (#1B4D89), underlined

4. **Run pandoc.** Convert the markdown to docx using the styled reference doc. Include `--toc` if requested.

5. **Post-process the docx.** Using python-docx:
   - Style tables: blue header row with white text, alternating row shading, light grey borders
   - Add page breaks before the "References" heading (if present)
   - Ensure all runs have Calibri font set

6. **Clean up.** Remove temporary reference doc.

7. **Report.** Print the output path on success.

## Dryrun Behaviour

When `--dryrun` / `-n` is passed:

```
[dryrun] Input:       /path/to/PROPOSAL.md
[dryrun] Output:      /path/to/PROPOSAL.docx
[dryrun] Title:       Building an Agentic Development Platform...
[dryrun] TOC:         yes (depth: 2)
[dryrun] Dependencies OK: pandoc 3.1.3, python-docx 1.2.0
[dryrun] Would generate styled .docx file
```

No files are created or modified.

## Edge Cases

- **Input file not found:** Exit 1 with `Error: file not found: <path>`
- **pandoc not installed:** Exit 1 with `Error: pandoc not found. Install with: sudo apt install pandoc`
- **python-docx not installed:** Exit 1 with `Error: python-docx not installed. Install with: pip install python-docx`
- **Output file already exists:** Overwrite without prompting (standard pipeline behaviour)
- **Markdown has no headings:** Use filename as title, skip TOC even if requested
- **Markdown has no tables:** Table styling step is a no-op
- **Markdown has no "References" section:** Page break insertion is a no-op

## Examples

```bash
# Basic conversion
md-to-docx PROPOSAL.md

# Custom output path and title
md-to-docx -o ~/Documents/proposal-v2.docx -t "Agent Platform Proposal" PROPOSAL.md

# With table of contents
md-to-docx --toc --toc-depth 3 SPEC.md

# Preview without creating files
md-to-docx --dryrun PROPOSAL.md
```