---
name: ck-markdown-novel-viewer
description: >
  Previews markdown files with rich rendering including Mermaid diagrams in a browser.
  Activate when user says 'preview this markdown', 'render this document', 'open markdown in browser',
  'visualize this plan', or 'show mermaid diagram'. Accepts markdown file paths and
  content with Mermaid, tables, and code blocks.
---

## Overview
Launches a local markdown preview server that renders documents with full Mermaid diagram support, syntax-highlighted code blocks, and styled tables — opening automatically in the default browser.

## When to Use
- Previewing plan files, architecture docs, or README files with diagrams
- Rendering Mermaid flowcharts, sequence diagrams, or ER diagrams visually
- Sharing a styled document view during presentations or reviews
- Verifying that generated markdown renders correctly before committing

## Don't Use When
- Document has no visual elements and plain text reading is sufficient
- Generating a static HTML export for deployment (use a static site tool)
- The file is not markdown (use appropriate viewer for PDF, DOCX, etc.)

## Steps / Instructions

### 1. Identify the Markdown File

Confirm the file path and check it exists:
```
Target file: /path/to/document.md
```

### 2. Launch the Viewer

Use the markdown-novel-viewer CLI or script:

```bash
# Via npx (no install required):
npx markdown-novel-viewer /path/to/document.md

# With custom port:
npx markdown-novel-viewer /path/to/document.md --port 4200

# Auto-open browser (default behavior):
npx markdown-novel-viewer /path/to/document.md --open
```

Or via the installed package:
```bash
md-viewer /path/to/document.md
```

### 3. Mermaid Diagram Syntax

The viewer renders fenced Mermaid blocks automatically:

````markdown
```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action A]
    B -->|No| D[Action B]
    C --> E[End]
    D --> E
```
````

````markdown
```mermaid
sequenceDiagram
    participant User
    participant API
    participant DB
    User->>API: POST /login
    API->>DB: SELECT user WHERE email=?
    DB-->>API: user record
    API-->>User: 200 OK + session token
```
````

````markdown
```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : included_in
```
````

### 4. Supported Features

| Feature | Syntax |
|---------|--------|
| Mermaid diagrams | ` ```mermaid ` fenced block |
| Syntax highlighting | ` ```typescript `, ` ```python `, etc. |
| Tables | GFM pipe tables |
| Task lists | `- [x]` / `- [ ]` |
| Callouts | `> **Note**`, `> **Warning**` |
| Math (if enabled) | `$inline$` / `$$block$$` |

### 5. Serving Multiple Files

To preview an entire directory (e.g., a plans folder):
```bash
npx markdown-novel-viewer /path/to/plans/ --index
```

This creates a file listing page with links to all `.md` files.

### 6. Integration with Plan Visuals

When generating diagrams as part of planning:
1. Write the markdown with Mermaid blocks to the plan's `visuals/` directory
2. Launch viewer pointing at that file
3. Browser opens automatically for immediate review

```
plans/260216-1304-my-feature/visuals/architecture.md
```

## Notes
- Viewer runs on `localhost:3000` by default; change port if occupied
- File changes hot-reload automatically — edit and see updates instantly
- Mermaid v11 syntax is supported; use ck-mermaidjs-v11 for diagram syntax reference
- Close the viewer with `Ctrl+C` in the terminal when done