▋
md-preview/SKILL.md

name: md-preview description: >- Preview local Markdown files or directories in a polished browser UI with live reload, file navigation, table of contents, syntax highlighting, and interactive Mermaid diagrams. Use when the user wants to open, render, inspect, or share a local Markdown preview.

md-preview

Run the skill's Node script: node ~/.claude/skills/md-preview/main.mjs, or install it once as a command — ln -s ~/.claude/skills/md-preview/main.mjs ~/.local/bin/md-preview — and call md-preview.

Usage

node ~/.claude/skills/md-preview/main.mjs <file-or-directory> [--host 127.0.0.1] [--port 0] [--open]
  • A directory opens README.md, readme.md, index.md, its first Markdown file, or its first supported image.
  • Supported images can be opened directly or selected from the file explorer; they use the same pan, zoom, fit, and fullscreen viewer as standalone Markdown images.
  • A file under ~/Documents uses ~/Documents as the explorer root; other files use their containing directory.
  • The bundled Marked module renders Markdown without network access. Highlight.js, Mermaid, and web fonts are optional CDN enhancements; failures leave readable code, diagram source, and system-font fallbacks.
  • Standalone Markdown images and Mermaid diagrams have out, in, fit, and full controls. Drag to pan; use +, -, 0, or f from the focused viewer, and pinch or Control/Command-scroll to zoom.
  • The server prints its local URL after it starts. Keep the process running while the user views the preview.

Workflow

Start the server on loopback (another host only if the user asks), open the printed URL when a browser surface is available, and confirm the page loads. Leave the process running and return the local URL. Feature-by-feature checks belong to node test.mjs and the Development notes, not to each preview.

Development

  • Edit this skill directory only; runtime skill entries (and any md-preview command on PATH) are symlinks into it. vendor/marked.esm.js is the pinned core renderer and vendor/marked.LICENSE carries its license.
  • Run node test.mjs after changes.
  • Keep oversized image canvases centered independently of their intrinsic layout width; grid safe-alignment can push a scaled image offscreen. Verify a wide image inline and fullscreen, then zoom and pan it.
  • #toc-aside is hidden for every image and for docs with under two headings. A hidden grid item leaves the grid entirely, so main inherits the 236px TOC column unless #layout collapses to one. Check a heading-less doc and an image at a viewport over 1120px after touching that grid.
  • Headless Chrome hangs on these pages — the live-reload EventSource never closes, so --virtual-time-budget never settles. Verify layout in a real browser.
  • Keep unsupported explorer entries inert. Supported image entries open in the preview shell rather than navigating to raw asset routes or triggering downloads.