mdgaze

A pretty and simple Markdown viewer & editor. Browse a folder of .md files in a clean tree, read them rendered, edit when you need to, save with ⌘S.

Why

You have a folder of notes, docs, or a project's docs/ directory and you just want to peek at them — rendered nicely, no setup, no editor extension, no static-site build step. Sometimes you also want to fix a typo and save it. That's mdgaze.

Features

• Folder tree of every .md / .markdown / .mdx file (including nested), filtered with a fuzzy search box.
• Full keyboard navigation in the tree (WAI-ARIA): arrows to move, ←/→ to collapse/expand or jump parent/child, Enter to open.
• GitHub-flavored Markdown rendering: tables, task lists, fenced code, ordered/unordered lists, blockquotes.
• Syntax highlighting for code blocks (powered by highlight.js).
• Edit mode with one-shortcut toggle (⌘E) and save (⌘S) — files are written back in place.
• New file flow (⌘N) — creates the file (with intermediate directories) and drops you straight into edit mode.
• Back navigation (⌘[) across markdown links — follow a link, click back to return.
• Inline image and source-code viewers — relative links to .png / .svg / .json / .ts / etc. open in the same window.
• Concurrent-edit detection — if a file changes on disk while open, save asks before overwriting.
• Auto theme that follows your OS light / dark preference.
• CLI launcher: mdgaze ./docs from anywhere in your terminal.
• Sandboxed renderer — full Chromium sandbox; FS access only inside the folder you opened, with symlink-resolved containment.
• Cross-platform builds: macOS (.dmg, .zip), Linux (AppImage, .deb, .rpm, .tar.gz), Windows (NSIS installer + portable .exe).

Install

From npm (recommended for the CLI)

npm install -g @dareia/mdgaze
mdgaze ./docs

The package is published under the @dareia scope; the CLI command after install is still mdgaze.

Pre-built binaries

Download the latest release for your platform from the Releases page and install it like any other desktop app.

From source

git clone https://github.com/dareia/mdgaze.git
cd mdgaze
npm install
npm start

Usage

mdgaze                # open the current directory
mdgaze ./docs         # relative path
mdgaze ~/notes        # absolute path
mdgaze --help
mdgaze --version

Keyboard shortcuts

| Action | macOS | Windows / Linux | | --------------------- | ------ | --------------- | | Open folder… | ⌘O | Ctrl+O | | New file… | ⌘N | Ctrl+N | | Toggle edit / preview | ⌘E | Ctrl+E | | Save | ⌘S | Ctrl+S | | Focus filter | ⌘F | Ctrl+F | | Back to previous file | ⌘[ | Ctrl+[ |

Once focus is in the tree (Tab into it), use ↑ / ↓ to move, → / ← to expand / collapse, Home / End to jump, Enter or Space to open.

Development

npm start             # build vendor bundles + launch
npm run dev           # alias for `npm start ./`
npm run lint          # ESLint flat-config check
npm test              # node:test unit suite (no extra deps)
npm run build:vendor  # rebundle renderer deps + preload + hljs themes

MDGAZE_DEVTOOLS=1 npm start opens DevTools attached. MDGAZE_DEBUG=1 mirrors the renderer console to your terminal.

Building distributables

npm run dist:mac     # .dmg + .zip (universal: x64 + arm64)
npm run dist:linux   # AppImage + .deb + .rpm + .tar.gz
npm run dist:win     # NSIS installer + portable .exe
npm run dist:all     # everything (run on macOS for full coverage)

Output lands in dist/. CI builds for all three platforms run on every tag — see .github/workflows/build.yml.

Code signing & notarization are not configured by default. To produce signed/notarized macOS builds and signed Windows installers, set the standard electron-builder env vars (CSC_LINK, CSC_KEY_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID, WIN_CSC_LINK, …) in your environment or as repository secrets. See the electron-builder code-signing guide.

Documentation

• docs/USAGE.md — using the app day-to-day.
• docs/DEVELOPMENT.md — running locally, regenerating icons, debugging.
• docs/ARCHITECTURE.md — how main / preload / renderer fit together.
• docs/RELEASING.md — building installers, cutting a release, publishing to npm, code signing.
• CONTRIBUTING.md — how to contribute.
• CHANGELOG.md — release notes.

Project layout

mdgaze/
├── bin/mdgaze.js              # CLI launcher (npm bin entry)
├── src/
│   ├── main.js                # Electron main process: window, menu, IPC, FS gates
│   ├── preload.js             # contextBridge source (bundled at runtime)
│   ├── preload-bundled.js     # esbuild output, loaded by main (gitignored)
│   ├── shared/
│   │   ├── ipc.js             # CHANNELS + MD_EXTENSIONS (CJS, used by main+preload)
│   │   └── safety.js          # executable-extension deny-list + helper
│   └── renderer/
│       ├── index.html         # markup, CSP meta, modal scaffolding
│       ├── styles.css         # entire UI theme (dark + light)
│       ├── app.js             # tree, viewer, editor, history, IPC plumbing
│       ├── lib/text.js        # pure DOM-free helpers (testable)
│       └── vendor/            # generated: marked, hljs, dompurify, hljs themes
├── test/                      # node:test unit specs (.mjs)
├── assets/                    # icons + logo
├── scripts/
│   ├── build-icons.py         # procedural icon generator
│   └── build-vendor.mjs       # bundles renderer deps + preload + copies hljs CSS
├── docs/                      # user & contributor docs
├── .github/workflows/         # cross-platform CI builds
├── eslint.config.mjs
├── package.json               # also holds electron-builder config
└── LICENSE

License

MIT © Dareia

Acknowledgements

mdgaze stands on:

• Electron
• marked — Markdown parser
• highlight.js — syntax highlighting
• DOMPurify — HTML sanitization
• electron-builder — packaging