markdown-novel-viewer

Background HTTP server rendering markdown files with calm, book-like reading experience.

⚠️ Installation Required

This skill requires npm dependencies. Run one of the following:

# Option 1: Install via ClaudeKit CLI (recommended)
ck init  # Runs install.sh which handles all skills

# Option 2: Manual installation
cd .opencode/skills/markdown-novel-viewer
npm install

Dependencies: marked, highlight.js, gray-matter

Without installation, you'll get Error 500: Error rendering markdown.

Purpose

Universal viewer - pass ANY path and view it:

• Markdown files → novel-reader UI with serif fonts, warm theme
• Directories → file listing browser with clickable links

Quick Start

# View a markdown file
node .opencode/skills/markdown-novel-viewer/scripts/server.cjs \
  --file ./plans/my-plan/plan.md \
  --open

# Browse a directory
node .opencode/skills/markdown-novel-viewer/scripts/server.cjs \
  --dir ./plans \
  --host 0.0.0.0 \
  --open

# Background mode
node .opencode/skills/markdown-novel-viewer/scripts/server.cjs \
  --file ./README.md \
  --background

# Stop all running servers
node .opencode/skills/markdown-novel-viewer/scripts/server.cjs --stop

Slash Command

Use /preview for quick access:

/preview plans/my-plan/plan.md    # View markdown file
/preview plans/                   # Browse directory
/preview --stop                   # Stop server

Features

Novel Theme

• Warm cream background (light mode)
• Dark mode with warm gold accents
• Libre Baskerville serif headings
• Inter body text, JetBrains Mono code
• Maximum 720px content width

Mermaid.js Diagrams

• Auto-renders mermaid code blocks as diagrams
• Theme-aware (light/dark mode support)
• Error display with source preview for debugging

Directory Browser

• Clean file listing with emoji icons
• Markdown files link to viewer
• Folders link to sub-directories
• Parent directory navigation (..)
• Light/dark mode support

Plan Navigation

• Auto-detects plan directory structure
• Sidebar shows all phases with status indicators
• Previous/Next navigation buttons
• Keyboard shortcuts: Arrow Left/Right

Keyboard Shortcuts

• T - Toggle theme
• S - Toggle sidebar
• Left/Right - Navigate phases
• Escape - Close sidebar (mobile)

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --file <path> | Markdown file to view | - | | --dir <path> | Directory to browse | - | | --port <number> | Server port | 3456 | | --host <addr> | Host to bind (0.0.0.0 for remote) | localhost | | --open | Auto-open browser | false | | --background | Run in background | false | | --stop | Stop all servers | - |

Architecture

scripts/
├── server.cjs               # Main entry point
└── lib/
    ├── port-finder.cjs      # Dynamic port allocation
    ├── process-mgr.cjs      # PID file management
    ├── http-server.cjs      # Core HTTP routing (/view, /browse)
    ├── markdown-renderer.cjs # MD→HTML conversion
    └── plan-navigator.cjs   # Plan detection & nav

assets/
├── template.html            # Markdown viewer template
├── novel-theme.css          # Combined light/dark theme
├── reader.js                # Client-side interactivity
├── directory-browser.css    # Directory browser styles

HTTP Routes

| Route | Description | |-------|-------------| | /view?file=<path> | Markdown file viewer | | /browse?dir=<path> | Directory browser | | /assets/* | Static assets | | /file/* | Local file serving (images) |

Dependencies

• Node.js built-in: http, fs, path, net
• npm: marked, highlight.js, gray-matter (installed via npm install)

Customization

Theme Colors (CSS Variables)

Light mode variables in assets/novel-theme.css:

--bg-primary: #faf8f3;      /* Warm cream */
--accent: #8b4513;          /* Saddle brown */

Dark mode:

--bg-primary: #1a1a1a;      /* Near black */
--accent: #d4a574;          /* Warm gold */

Content Width

--content-width: 720px;

Remote Access

To access from another device on your network:

# Start with 0.0.0.0 to bind to all interfaces
node server.cjs --file ./README.md --host 0.0.0.0 --port 3456

When using --host 0.0.0.0, the server auto-detects your local network IP and includes it in the output:

{
  "success": true,
  "url": "http://localhost:3456/view?file=...",
  "networkUrl": "http://192.168.2.75:3456/view?file=...",
  "port": 3456
}

Use networkUrl to access from other devices on the same network.

Troubleshooting

Port in use: Server auto-increments to next available port (3456-3500)

Images not loading: Ensure image paths are relative to markdown file

Server won't stop: Check /tmp/md-novel-viewer-*.pid for stale PID files

Remote access denied: Use --host 0.0.0.0 to bind to all interfaces

Mermaid.js Diagrams

Usage

Use fenced code blocks with mermaid language:

```mermaid
pie title Traffic Sources
    "Organic" : 45
    "Direct" : 30
    "Referral" : 25
```

Supported Diagram Types

| Type | Syntax | Use Case | |------|--------|----------| | Flowchart | flowchart LR/TB/TD | Process flows, decision trees | | Sequence | sequenceDiagram | API interactions, message flows | | Pie | pie title "..." | Distribution data | | Gantt | gantt | Project timelines | | XY Chart | xychart-beta | Bar/line charts | | Mindmap | mindmap | Idea hierarchies | | Quadrant | quadrantChart | 2x2 matrices |

Validating Mermaid Snippets

Quick validation: Use the Mermaid Live Editor to test syntax.

Common errors and fixes:

| Error | Cause | Fix | |-------|-------|-----| | Parse error | Invalid syntax | Check diagram type declaration | | Unknown diagram type | Typo in declaration | Use exact type: flowchart, not flow | | Expecting token | Missing quotes/brackets | Ensure balanced delimiters | | UnknownDiagramError | Empty or malformed block | Add valid diagram content |

Fixing Common Issues

1. Flowchart arrows

%% Wrong: A -> B
%% Correct:
flowchart LR
    A --> B

2. Pie chart values

%% Wrong: "Label": 50%
%% Correct:
pie title Sales
    "Product A" : 50
    "Product B" : 30

3. XY Chart data format

xychart-beta
    title "Monthly Sales"
    x-axis [Jan, Feb, Mar]
    y-axis "Revenue" 0 --> 100
    bar [30, 45, 60]

4. Sequence diagram participants

sequenceDiagram
    participant A as Client
    participant B as Server
    A->>B: Request
    B-->>A: Response

Debug Mode

When a diagram fails to render, the viewer shows:

• Error message
• Expandable source code preview
• Line number where parsing failed (when available)

Fix the syntax and refresh the page to re-render.