mindmap

simple mindmap app

Features

• run via npx @fingerskier/mindmap .
  • uses markdown files in the given directory as nodes in the mindmap
  • branches are sub-directories, leaves are md files
• the nodes have a short slug atop them
• clicking a node opens a modal popup which can can toggle between rendered markdown and an editor
• shift+click shows/hides child nodes/branches of that node
• ctrl+click adds a child:
  • if no children then create a sub-dir and move that node's md file into it
  • if existing children then just create a new md file
• right-click context menu
  • delete

Architecture

• browser app over a localhost server (local-only so security is out-of-scope)
• watches file changes and updates in response

Usage

npx @fingerskier/mindmap [dir] [--port 6463] [--no-open]

• dir — directory of markdown files to map (defaults to the current directory)
• --port — port to serve on (default 6463, which is MIND on a phone keypad). If the port is busy, mindmap automatically falls back to the next free port and prints the one it used.
• --no-open — don't launch a browser (by default mindmap opens the app in your system default browser on startup)

The app opens automatically; otherwise browse to http://localhost:<port>.

Interactions

• click a node — open a modal. Leaves toggle between rendered markdown and an editor (Save writes back to disk) and can be renamed via the filename field (Rename; a missing .md extension is added, and Rename is hidden while there are unsaved edits — save first). Branches list their children and let you rename the folder the same way.
• shift+click a branch — show/hide its children
• ctrl+click (or ⌘+click) a node — add a child. A leaf with no children is first converted into a branch: a sub-directory is created and the node's .md file is moved into it. A branch gets a new untitled.md.
• right-click a node — context menu with Delete (non-empty branches must be emptied first)

These controls are also listed in the collapsible ? help panel in the bottom-right corner.

Edits made directly on disk are picked up live via a file watcher and pushed to the browser over a WebSocket.

Development

npm install
npm run dev         # Vite dev server (UI) with HMR
npm run dev:server  # API + WebSocket server for the current directory
npm test            # Vitest unit tests (server file operations)
npm run build       # runs the tests (prebuild) then bundles the SPA into dist/
npm run deploy      # rebuilds dist/ (predeploy) then `npm publish --access public`

build is gated by a prebuild hook that runs the test suite, and deploy is gated by a predeploy hook that rebuilds dist/ — so a publish always ships a freshly built, tested bundle. Bump the (date-based YYYY.M.D) version and npm login before npm run deploy.

The published package ships the prebuilt dist/ alongside bin/ and server/, so npx needs no build step. React, D3, marked, and CodeMirror are dev-only — they are bundled at build time; the installed runtime depends on express, ws, and chokidar.