antigravity-claudekit/skills/ck-markdown-novel-viewer/SKILL.md

name, description

name	description
ck-markdown-novel-viewer	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:

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

md-viewer /path/to/document.md

3. Mermaid Diagram Syntax

The viewer renders fenced Mermaid blocks automatically:

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

```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
```

```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):

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