notebook-md

A read-only, multi-project markdown viewer with live reload, Mermaid diagrams, frontmatter support, and fast file/content search.

Quickstart

Try it in 5 seconds — no config file needed:

npx notebook-md ~/your-notes

This boots an ephemeral session against that path. Nothing is written to disk.

Keep it

npm i -g notebook-md

notebook add ~/notes
notebook add ~/work/docs --name "Work Docs"
notebook serve

Then open http://localhost:9001.

CLI reference

notebook serve [--config <path>]          # long-running server (default behavior)
notebook add <path> [--name <name>]       # append a project to the config file
notebook remove <name|index>              # remove a project from the config file
notebook list                             # print configured projects
notebook <path>                           # ephemeral single-project session, no config read/write
notebook                                  # alias for `notebook serve`

Features

• Multi-project — switch between configured project roots in the UI, or pass a path for an ephemeral one-off session.
• Markdown rendering — GFM, syntax-highlighted code, and Mermaid diagrams (lazy-loaded).
• Embedded images & assets — relative links in markdown resolve against the current file, so PNG/JPG/SVG/PDF/etc. render inline.
• YAML frontmatter parsed into a collapsible metadata panel.
• Fast search — filename and full-text, powered by ripgrep with a pure-JS fallback. Live highlighting in the open document.
• File explorer with full keyboard navigation, auto-reveal of the active file, and .gitignore-aware scanning.
• Live reload — filesystem watcher updates the open document on external edits; config hot-reload updates the project list without a restart.

Plus: dark mode, resizable sidebar, URL-addressable state (refresh/bookmark restores the exact view), copy-to-clipboard for code blocks, cross-platform (macOS / Linux / Windows). Read-only by design — notebook never writes to your files.

Keyboard shortcuts

| Key | Action | | --- | --- | | ⌘K / Ctrl+K | Search filenames | | ⌘⇧K / Ctrl+Shift+K | Search file content | | Esc | Close mobile drawer / search | | ↑ ↓ | Move selection in the file tree | | → ← | Expand / collapse directory | | Enter | Open file / toggle directory | | Home End | Jump to first / last entry |

Configuration

Config discovery order:

1. --config <path> if passed to notebook serve
2. ~/.config/notebook/config.json
3. Built-in defaults (empty project list, port 9001)

notebook add always writes to ~/.config/notebook/config.json (creating it if needed), unless --config is passed.

Example

{
  "port": 9001,
  "projects": [
    {
      "name": "Work Docs",
      "path": "~/work/docs",
      "include": ["guides", "runbooks", "architecture"],
      "exclude": ["guides/drafts"]
    },
    {
      "name": "Personal Notes",
      "path": "~/notes"
    }
  ],
  "watcher": {
    "usePolling": false
  }
}

Project fields

| Field | Type | Description | | --- | --- | --- | | name | string | Display name shown in the project switcher. | | path | string | Absolute or ~-prefixed path to the project root. | | include | string[] (optional) | Path prefixes (relative, POSIX separators) to expose. If set, only files whose relative path is at or under one of these prefixes are shown. | | exclude | string[] (optional) | Path prefixes to hide. Exclude beats include. |

Supported file formats are tracked in src/supportedFormats.ts. Today that is just .md.

License

MIT