Preview

Install

npm i -g @astlw/peekmd

Requires Node.js 18+.

Features

Feature	Summary	Why it matters
Live reload	Real-time file events over WebSocket; open file preview refreshes on add/change/unlink.	Instant feedback while editing files.
Folder groups (multi-folder)	Sidebar shows each linked folder as a separate group; when folder basenames collide a compact path is shown to disambiguate.	Keep multiple projects side-by-side without confusion.
File tree	Per-folder collapsible file tree with relative paths; click a file to render Markdown in the preview.	Fast navigation and focused previews.
Ignore patterns (glob)	Glob-only patterns (picomatch) applied to watcher, search, and tree.	Simple, consistent filtering across the app. Quote globs in shells.
Search	Lightweight full-text substring search across filenames and file contents.	Fast, low-overhead lookup for most small/medium projects.
Markdown + Mermaid	Renders GFM and client-side Mermaid diagrams inside mermaid fences.	Rich previews without server-side rendering.
Daemon & CLI	Start/stop/status plus --json machine-readable output for scripts and agents.	Integrates with workflows and automation.

Config

Linked folders and ignore patterns are stored in:

~/.peekmd.json

{
    "folders": ["/Users/you/docs", "/Users/you/notes"],
    "ignore": ["**/node_modules/**", "**/dist/**", "**/*.draft.md"]
}

Created automatically on first use. Can be edited manually.

CLI Commands

# Server
peekmd start                        # start server (daemon)
peekmd stop                         # stop server
peekmd status                       # check server status
peekmd open                         # open browser (starts server if not running)
PORT=3000 peekmd start              # custom port (default: 4000)

# Folder management
peekmd link <dir> [dir2] ...        # persist folders to config
peekmd unlink <dir> [dir2] ...      # remove folders from config
peekmd list                         # show linked folders

# Ignore patterns (glob syntax)
peekmd ignore <pattern> ...         # ignore folders/files by glob pattern
peekmd unignore <pattern> ...       # remove an ignore pattern
peekmd ignored                      # show all active ignore patterns

# Structured Output (Useful for integrating with scripts or other tools)
peekmd list --json                  # linked folders as JSON
peekmd ignored --json               # ignore patterns as JSON
peekmd status --json                # server status as JSON
peekmd search <query>               # search files and content (JSON)
peekmd files                        # list all markdown files (JSON)

peekmd --help                       # print help

Ignore Patterns

Ignore patterns let you exclude folders or files from the file tree, search, and live-reload. Patterns are stored in ~/.peekmd.json and apply globally. All patterns use glob syntax (picomatch).

Examples:

peekmd ignore "**/node_modules/**"         # ignores all node_modules folders
peekmd ignore "**/dist/**" "**/build/**"   # ignore multiple patterns
peekmd ignore "**/*.draft.md"              # ignores all .draft.md files
peekmd ignore "docs/private/**"            # ignores everything under docs/private
peekmd ignore "*.tmp"                      # ignores .tmp files at any depth

How they work:

Ignore patterns are global and applied to every linked folder. Each pattern is tested against the file path relative to that folder’s root.

Linked Folder	File Path	Relative Path	Pattern	Matches
/Users/you/project	/Users/you/project/docs/private/a.md	docs/private/a.md	docs/private/**	✅ Yes
/Users/you/project	/Users/you/project/README.md	README.md	docs/private/**	❌ No
/Users/you	/Users/you/project/docs/private/a.md	project/docs/private/a.md	docs/private/**	❌ No
/Users/you	/Users/you/project/docs/private/a.md	project/docs/private/a.md	**/docs/private/**	✅ Yes
/Users/you/project	/Users/you/project/build/tmp.log	build/tmp.log	**/build/**	✅ Yes
/Users/you/project	/Users/you/project/src/file.draft.md	src/file.draft.md	**/*.draft.md	✅ Yes
/Users/you/project	/Users/you/project/foo.tmp	foo.tmp	**/*.tmp	✅ Yes

Default patterns (applied automatically):

**/node_modules/**
**/.git/**
**/dist/**
**/build/**
**/.next/**
**/__pycache__/**
...

NOTE

• Ignore patterns are glob-only (picomatch). Regex/exact-name modes are not supported.
• Search is intentionally simple (substring per-line) for clarity and low resource usage.