Skip to content

CLAUDE.md

Latest commit

 

History

History
84 lines (71 loc) · 3.37 KB

CLAUDE.md

File metadata and controls

84 lines (71 loc) · 3.37 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Install dependencies

npm install

Run the viewer

# Single file (auto-reload enabled by default)
./viewmd.js <markdown-file>
# or
node viewmd.js <markdown-file>

# Multiple files (with page breaks, auto-reload enabled)
./viewmd.js <file1.md> <file2.md> <file3.md>
# or
node viewmd.js <file1.md> <file2.md> <file3.md>

# Snapshot mode (render once without watching)
./viewmd.js --snapshot <markdown-file>
# or
./viewmd.js -s <file1.md> <file2.md>

Install globally

npm install -g .
# Then use from anywhere:
viewmd <markdown-file>
# or for multiple files:
viewmd <file1.md> <file2.md> <file3.md>
# or for snapshot mode:
viewmd --snapshot <file1.md> <file2.md> <file3.md>

CLI Options

  • -p, --port <number>: Use specific port instead of random
  • --no-open: Don't automatically open browser
  • -k, --keep-alive: Keep server running after browser closes
  • -s, --snapshot: Render once without watching for changes (disables auto-reload)

Architecture

This is a CLI tool that renders one or more markdown files in a browser with GitHub-flavored markdown and Mermaid diagram support. When multiple files are provided, they are combined into a single HTML document with CSS page breaks for clean PDF generation.

Core Flow

  1. viewmd.js - CLI entry point that handles command-line arguments and file validation for one or more files
  2. index.js - Core logic that:
    • Reads all markdown files
    • Converts each markdown file to HTML using marked with GFM plugins
    • Creates an Express server that serves a single HTML page
    • For multiple files: generates table of contents and combines content with page breaks
    • Embeds the rendered markdown in a GitHub-styled HTML template
    • Includes Mermaid.js for diagram rendering
    • Auto-opens browser and manages server lifecycle

Key Implementation Details

  • The open package requires special handling: require('open').default || require('open')
  • Mermaid diagrams are detected by language-mermaid code blocks and converted client-side
  • Server auto-shuts down when browser tab closes via beforeunload event
  • Uses GitHub markdown CSS and Highlight.js for authentic GitHub rendering
  • Multi-file support: Accepts multiple file arguments and combines them with CSS page breaks
  • Table of Contents: Auto-generated for multiple files with anchor links
  • Print optimization: CSS @media print rules ensure clean page breaks when generating PDFs
  • Auto-reload: Enabled by default (disable with --snapshot):
    • Uses chokidar for cross-platform file watching with debouncing (300ms)
    • Server-Sent Events (SSE) for one-way server-to-client communication
    • Client-side EventSource with automatic reconnection and exponential backoff
    • Brief notification flashes when page reloads due to file changes
    • Full page reload on file changes to ensure consistency

Dependencies

  • marked: Markdown parser with GFM support configured
  • express: Serves the HTML page
  • open: Opens browser automatically
  • commander: CLI argument parsing
  • marked-gfm-heading-id: Adds GitHub-style heading anchors
  • marked-highlight + highlight.js: Syntax highlighting for code blocks
  • chokidar: Cross-platform file watching for auto-reload functionality