126 lines
3.4 KiB
Markdown
126 lines
3.4 KiB
Markdown
---
|
|
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
|