[file-or-directory] Markdown file or directory
Path to one Markdown file for reader mode or one directory for browsing. Relative paths resolve from the current working directory; omit when stopping running viewers.
Ctrl K
Quick Ref / Command
Engineer Kit
/ak:markdown-novel-viewer
Calm Markdown reader
Serve Markdown files and directories as a calm browser reader with warm themes, progress, plan navigation, keyboard shortcuts, and live Mermaid diagrams.
01
Install dependencies
02
Choose input path
03
Start viewer server
04
Render reading UI
Rule 01
A distraction-free reader for long-form Markdown, not a self-contained HTML generator
Rule 02
One path works for both files and directories
Rule 03
Mermaid failures should reveal the source and the fix path
Rule 04
Plan navigation must stay comfortable on desktop and mobile
Execution Map
Core lanes from input to output, aligned with the command's real execution path.
01
Start
Input, scope, route
- 1 Install dependencies Ensure the skill directory has npm dependencies installed: marked, highlight.js, and gray-matter.
- 2 Choose input path Accept any Markdown file for reader mode or any directory for the clickable browser view.
02
Work
Agent / skill execution
- 3 Start viewer server Run the Node server with file or directory routing, using dynamic ports when the default is busy.
- 4 Render reading UI Convert Markdown into a warm serif reader with syntax highlighting, narrow content width, and theme toggle.
03
Verify
Gate, review, validation
- 5 Enhance navigation For plan folders, detect plan structure and expose sidebar accordions, status badges, previous/next buttons, and mobile bottom sheet.
- 6 Render diagrams Auto-render mermaid code blocks, let readers expand diagrams full width, and show parse errors with source preview.
04
Close
Report, handoff, artifact
- 7 Support reading controls Expose progress bar, auto-hide header, shortcuts for help, theme, sidebar, phase navigation, and modal close.
- 8 Troubleshoot access Report install errors, stale PID files, image-path problems, remote host binding, or Mermaid syntax fixes clearly.
Syntax, arguments, subcommands
How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.
Syntax
/ak:markdown-novel-viewer [file-or-directory] [--file <path>|--dir <path>] [--port <number>] [--host <addr>] [--open|--no-open] [--background|--foreground] [--stop]Arguments
Shared options
--file <path> Serve file
Serve an explicit Markdown file at the reader route and allow its parent directory for local assets.
/ak:markdown-novel-viewer --file ./plans/my-plan/plan.md --open--dir <path> Browse directory
Serve an explicit directory browser. Hidden entries and directories named deprecated are omitted from the listing.
/ak:markdown-novel-viewer --dir ./plans --open--port <number> Starting port
Request the starting HTTP port. The default is 3456 and occupied ports are scanned upward through 3500.
/ak:markdown-novel-viewer ./README.md --port 3460 --open--host <addr> Bind host
Choose the bind address. Keep localhost for local-only reading; 0.0.0.0 exposes the viewer on available network interfaces.
/ak:markdown-novel-viewer ./README.md --host 0.0.0.0 --open--no-open Do not open browser
Suppress the implementation default browser launch; use for deterministic, headless, or URL-only runs.
/ak:markdown-novel-viewer ./README.md --no-open--open Open browser
Launch the browser after the server is ready.
/ak:markdown-novel-viewer ./README.md --open--background Background server
Spawn a detached child process, write PID state under the system temporary directory, and return JSON startup details.
/ak:markdown-novel-viewer ./README.md --background --open--foreground Foreground server
Keep the server attached for a runtime-managed background task and emit machine-readable startup JSON.
/ak:markdown-novel-viewer ./README.md --foreground --no-open--stop Stop viewers
Stop every markdown-novel-viewer instance represented by discovered PID files; confirm shared instances before using it.
/ak:markdown-novel-viewer --stopSample Prompt
Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.
Read a long Markdown file Recommended
/ak:markdown-novel-viewer plans/feature-auth/plan.md- Use when:
- Use when long Markdown is easier to review in a distraction-free browser reader.
- Expected:
- The skill serves the file in reader mode with warm light/dark themes, reading progress, auto-hiding header, syntax highlighting, and Mermaid blocks rendered live.
Browse a directory
/ak:markdown-novel-viewer plans/feature-auth- Use when:
- Use when you need a clickable browser view for a folder of Markdown files and subfolders.
- Expected:
- The skill serves a directory browser with parent navigation, folder links, Markdown links that open in the reader, and matching light/dark styling.
Review a plan folder
/ak:markdown-novel-viewer plans/feature-auth- Use when:
- Use when a plan directory has phase files and you want structured navigation while reading.
- Expected:
- The viewer detects plan structure and adds accordion sidebar navigation, status badges, previous/next phase buttons, and a mobile bottom sheet/FAB.
Read docs with diagrams
/ak:markdown-novel-viewer docs/runbooks- Use when:
- Use for RFCs, runbooks, specs, reports, or book-length docs that include Mermaid diagrams.
- Expected:
- Markdown documents open in the book-like reader; Mermaid diagrams render theme-aware, can expand full width, and show source/error details when parsing fails.
Handled Scope
- Long-form Markdown review
- Plan folder navigation
- Live Mermaid rendering
- Responsive reader UI
- Local HTTP file browsing
Artifacts Produced
Viewer Output
Pattern
Local browser URL for /view or /browse Markdown reader, directory browser, plan navigation, live diagrams, and remote-access URL when host is bound to 0.0.0.0.