Claude-skill-registry-data markdown-novel-viewer

View markdown files with calm, book-like reading experience via HTTP server. Use for long-form content, documentation preview, novel reading, report viewing, distraction-free reading.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry-data

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry-data "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/markdown-novel-viewer-hoanghd218-landing-page-ai-kien" ~/.claude/skills/majiayu000-claude-skill-registry-data-markdown-novel-viewer && rm -rf "$T"

manifest: data/markdown-novel-viewer-hoanghd218-landing-page-ai-kien/SKILL.md

source content

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.