[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1431":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":16,"starSnapshotCount":16,"syncStatus":35,"lastSyncTime":36,"discoverSource":37},1431,"zennotes","ZenNotes\u002Fzennotes","ZenNotes","Keyboard-first local Markdown notes with Vim motions, diagrams, and MCP integration.","https:\u002F\u002Fzennotes.org",null,"TypeScript",555,26,1,15,0,282,284,330,846,8.29,"MIT License",false,"main",[26,27,28,29,30,31],"electron","local-first","markdown","mcp","notes","vim","2026-06-12 02:00:27","# ZenNotes\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"apps\u002Fdesktop\u002Fbuild\u002Ficon.png\" alt=\"ZenNotes app icon\" width=\"160\">\n\u003C\u002Fp>\n\nZenNotes is a keyboard-first Markdown notes app with a shared product core and multiple runtimes:\n\n- a desktop app built with Electron\n- a self-hosted web app backed by a Go server\n- a future hosted deployment mode built on the same web\u002Fserver stack\n\nZenNotes keeps your notes as ordinary Markdown files on disk. It adds Vim-friendly editing, split and preview workflows, tasks, tags, archive\u002Ftrash, diagrams, search, daily notes, and MCP integration on top of the files you already own.\nOn macOS, the first-party `zen` CLI also powers launcher workflows such as the Raycast extension.\n\nDownload the latest desktop build from [GitHub Releases](https:\u002F\u002Fgithub.com\u002FZenNotes\u002Fzennotes\u002Freleases\u002Flatest).  \nWebsite: [zennotes.org](https:\u002F\u002Fzennotes.org)\n\nDetailed in-repo documentation lives under [docs\u002FREADME.md](docs\u002FREADME.md).\n\n## What ZenNotes is for\n\n- writing and organizing plain-file Markdown notes without a database\n- moving quickly with keyboard-first navigation and Vim motions\n- working across edit, split, and preview modes without losing context\n- keeping tasks, tags, search, archive, trash, and quick capture inside the same vault\n- rendering math and diagrams directly from Markdown\n- exposing the vault to MCP-capable tools through a first-party server\n- searching and opening notes from terminal scripts or Raycast on macOS\n- self-hosting the app on your own machine or home server\n\n## Product modes\n\nZenNotes now ships from one monorepo with one shared app core.\n\n- `desktop`: Electron shell, native menus, updater, floating windows, desktop packaging\n- `self-hosted`: browser frontend plus Go server, suitable for home servers and LAN use\n- `hosted`: planned as the same web\u002Fserver stack with auth and multi-user storage added later\n\nThe source of truth for user-facing features is the shared UI in `packages\u002Fapp-core`.\n\n## Core ideas\n\n### Plain files first\n\nEvery note is a normal `.md` file inside a chosen vault. ZenNotes does not store note content in a hidden database.\n\n### Keyboard-first by default\n\nZenNotes assumes you want to move fast:\n\n- first-class Vim mode\n- leader-key flows\n- command palette\n- pane and tab motion\n- local ex commands\n- built-in help\n\n### Preview is part of the workflow\n\nZenNotes supports:\n\n- edit mode\n- preview mode\n- split mode\n- pinned reference panes\n- detached note windows on desktop\n\n### Shared vault, shared tooling\n\nZenNotes includes a first-party MCP server and desktop install flows for compatible clients, so tools can work on the same vault you do instead of a copy.\n\n## Feature overview\n\n### Notes, folders, and lifecycle\n\nZenNotes can:\n\n- create, rename, duplicate, move, archive, unarchive, trash, restore, and reveal notes and folders\n- watch the vault for external changes\n- reopen your workspace layout with tabs and panes\n\nSystem folders still exist, but the vault model is more flexible now:\n\n- `quick`, `archive`, and `trash` remain built-in lifecycle areas\n- the main notes area can be either:\n  - `inbox\u002F`\n  - the vault root directly, for Obsidian-style flat vaults\n\nThe built-in folder labels are also customizable in the UI without changing the underlying internal ids.\n\n### Daily notes\n\nDaily notes are optional and can be enabled from Settings.\n\n- when enabled, ZenNotes can open or create today's note automatically\n- the title is a simple ISO date like `2026-04-21`\n- daily notes live in a dedicated directory under your primary notes area\n- the default directory is `Daily Notes`\n\n### Editor and preview\n\nThe editor stack is CodeMirror 6 with a Markdown-oriented workflow:\n\n- live preview behavior in the editor\n- heading folding\n- outline extraction and jumps\n- configurable line numbers\n- configurable line-height and typography controls\n- syntax highlighting for fenced code blocks\n- wiki links, callouts, tables, footnotes, and local embeds\n- Vim block cursor and keyboard navigation\n\nPreview and split mode support:\n\n- GitHub-flavored Markdown\n- KaTeX math\n- Mermaid\n- TikZ\n- JSXGraph\n- function-plot\n- callouts\n- footnotes\n- wiki links and backlinks\n\n### Search, tasks, tags, and built-in views\n\nZenNotes includes:\n\n- note search by title and path\n- vault-wide text search\n- tags view\n- tasks view\n- archive view\n- trash view\n- quick notes view\n- built-in help\u002Fmanual\n\nVault text search can use the built-in engine, `ripgrep`, or `fzf`, with auto-detection and optional custom binary paths.\n\nThe desktop app also ships a `zen` command-line companion for list, read, search, capture, edit, archive\u002Ftrash, task, folder, and MCP workflows. On macOS, ZenNotes can install its Raycast extension locally from Settings -> CLI, avoiding the Raycast Store review path. The integration uses the CLI plus `zennotes:\u002F\u002F` deep links to search notes, open them in the main app, open them in floating windows, archive\u002Funarchive, move notes to Trash, reveal files in Finder, and copy note paths or wikilinks.\n\n### Obsidian-friendly vault support\n\nZenNotes now works better with existing Obsidian-style vaults.\n\n- primary notes can live at the vault root instead of requiring `inbox\u002F`\n- loose files anywhere in the vault are surfaced as files\u002Fassets\n- embedded files like `![[image.png]]` resolve more like Obsidian\n- new referenced files default to the vault root instead of a required attachments folder\n- legacy `attachements\u002F` and `_assets\u002F` folders are still recognized\n\nThis means imported vaults with top-level notes, folders, and loose images\u002Ffiles behave much more naturally.\n\n### Files and local assets\n\nZenNotes supports local files in notes and in the sidebar\u002Flist views.\n\n- local images and files can appear directly in the vault tree\n- images, SVGs, videos, audio, PDFs, and other media open inside ZenNotes tabs or reference panes instead of being handed off to the OS by default\n- desktop context menus include reveal-in-file-manager actions\n- desktop uses Finder on macOS and the platform file manager on Windows\u002FLinux\n- watcher updates now include non-Markdown file changes, so deleting files externally updates the UI without a manual refresh\n\nSidebar multi-select supports platform modifiers: use Cmd\u002FCtrl-click to toggle individual notes or folders, Shift-click to select a visible range, then use the context menu to apply actions such as open in tabs, move, archive, trash, restore, delete folders, copy paths, or drag the selected group to a folder.\n\n### Themes, fonts, and customization\n\nThe settings surface includes:\n\n- theme families and light\u002Fdark\u002Fauto modes\n- interface, text, and monospace font selection\n- editor font size and line-height controls\n- preview and editor width controls\n- content alignment\n- keymap overrides\n- Vim toggles and leader hint behavior\n- search backend selection\n- vault layout settings\n- daily notes settings\n- system-folder display labels\n\n## Desktop vs web\n\nBoth runtimes share the same core app, but they do not expose identical platform features.\n\nDesktop-only features include:\n\n- native menus\n- app updater\n- floating note windows\n- `zen` CLI install\u002Funinstall flow\n- local Raycast extension installation on macOS\n- MCP install\u002Funinstall flows for supported clients\n- reveal in Finder \u002F platform file manager\n- packaging and signed releases\n\nWeb\u002Fself-hosted mode includes:\n\n- the same shared note UI and workflows\n- a Go backend for vault access and file watching\n- a server-side vault picker\u002Fbrowser\n- browser access on a LAN or home server\n\n## Monorepo layout\n\nZenNotes now uses a single monorepo.\n\n```text\napps\u002F\n  desktop\u002F   Electron shell, preload, updater, packaging\n  web\u002F       Vite\u002FPWA shell and HTTP bridge\n  server\u002F    Go server for self-hosted and hosted deployments\npackages\u002F\n  app-core\u002F        Shared React application and renderer logic\n  bridge-contract\u002F Typed runtime contract between UI and host\n  shared-domain\u002F   Shared types and note\u002Ftask\u002Fview models\n  shared-ui\u002F       Reusable UI primitives\ntooling\u002F\n  scripts\u002F         Shared tooling hooks and migration scripts\ndocs\u002F\n```\n\nRead [docs\u002Fmonorepo-architecture.md](docs\u002Fmonorepo-architecture.md) for the architectural boundary between the shared app core and the platform-specific shells.\n\n## Quick start\n\n### Requirements\n\n- Node.js 22+\n- npm\n- Go 1.22+ for the server build path\n- Docker optional, for self-hosting\n\n### Install dependencies\n\n```bash\nnpm ci\n```\n\n## Local development\n\n### Desktop app\n\n```bash\nnpm run dev:desktop\n```\n\nor:\n\n```bash\nmake desktop\n```\n\n### Web client\n\n```bash\nnpm run dev:web\n```\n\nor:\n\n```bash\nmake web-dev\n```\n\n### Go server\n\n```bash\nnpm run dev:server\n```\n\nor:\n\n```bash\nmake server-dev\n```\n\n### Web + server together\n\n```bash\nnpm run dev:web-stack\n```\n\nor:\n\n```bash\nmake web-stack\n```\n\nImportant dev note:\n\n- the browser app and the Go server are separate processes in dev mode\n- frontend-only changes usually need only the web dev server\n- backend changes need the Go server restarted\n- if the web client is newer than the running server, ZenNotes now shows a clearer error instead of raw 404 noise for newer API flows like the vault picker\n\n## Root scripts\n\nFrom the repository root:\n\n| Script                  | Purpose                                         |\n| ----------------------- | ----------------------------------------------- |\n| `npm run dev`           | Alias for `npm run dev:desktop`                 |\n| `npm run dev:desktop`   | Run the Electron desktop app in development     |\n| `npm run dev:web`       | Run the Vite web client                         |\n| `npm run dev:server`    | Run the Go server                               |\n| `npm run dev:web-stack` | Run web + server development together           |\n| `npm run start`         | Start the built desktop app                     |\n| `npm run typecheck`     | Run monorepo typechecks                         |\n| `npm run test`          | Run monorepo tests                              |\n| `npm run test:run`      | Run the full test suite                         |\n| `npm run build`         | Build the monorepo and then build the Go server |\n| `npm run build:prod`    | Typecheck + test + build                        |\n| `npm run pack`          | Desktop packaged output                         |\n| `npm run dist:mac`      | Build macOS desktop distributables              |\n| `npm run dist:win`      | Build Windows desktop distributables            |\n| `npm run dist:linux`    | Build Linux desktop distributables              |\n\n## Makefile commands\n\nThe root `Makefile` provides a simpler interface:\n\n| Command              | Purpose                                                 |\n| -------------------- | ------------------------------------------------------- |\n| `make install`       | Install workspace dependencies                          |\n| `make desktop`       | Run the Electron app in dev mode                        |\n| `make web-dev`       | Run the web client                                      |\n| `make server-dev`    | Run the Go server                                       |\n| `make web-stack`     | Run web + server together                               |\n| `make build`         | Build the full monorepo                                 |\n| `make desktop-build` | Build the Electron app                                  |\n| `make web-build`     | Build `apps\u002Fweb`                                        |\n| `make server-build`  | Build `apps\u002Fserver` with the latest embedded web bundle |\n| `make up`            | Build and start the self-hosted Docker stack            |\n| `make down`          | Stop the Docker stack                                   |\n| `make restart`       | Restart the Docker stack                                |\n| `make logs`          | Follow Docker logs                                      |\n| `make status`        | Show Docker status                                      |\n| `make open`          | Open the self-hosted app in a browser                   |\n| `make rebuild`       | Force a full Docker rebuild                             |\n| `make nuke`          | Remove local Docker image\u002Fbuild output                  |\n| `make clean`         | Remove local web\u002Fserver build output                    |\n\nRun `make help` to print the same summary.\n\n## Self-hosting with Docker\n\n### Start the self-hosted app\n\n```bash\nmake up\n```\n\nThen open:\n\n- [http:\u002F\u002Flocalhost:7878](http:\u002F\u002Flocalhost:7878)\n\n### Default Docker mounts\n\nWhen you start Docker with `make up`, ZenNotes mounts:\n\n- host `.\u002Fvault` -> container `.\u002Fvault`'s absolute host path\n- host `.\u002Fdata` -> container `\u002Fdata`\n\nIn practice, that means the container sees the vault at the same absolute path you chose on the host, instead of rewriting it to `\u002Fworkspace`.\n\nThe server stores its config under `\u002Fdata\u002Fserver.json` by default.\n\n### Default Docker security behavior\n\nThe self-hosted Docker flow is now secure by default:\n\n- the published port binds to `127.0.0.1` unless you override it\n- ZenNotes generates a bootstrap auth token on first `make up` and stores it in `.\u002Fdata\u002Fauth-token`\n- the browser version signs in with that token once, then uses an `HttpOnly` session cookie\n- the container runs as your local UID\u002FGID by default, with a read-only root filesystem, `no-new-privileges`, and dropped Linux capabilities\n\nUseful env vars:\n\n- `ALLOW_INSECURE_NOAUTH=1`: only use this if you intentionally want to disable auth\n- `ZENNOTES_ALLOWED_ORIGINS`: explicit browser origin allowlist\n- `ZENNOTES_BROWSE_ROOTS`: restricts which server-side directories the picker can browse\n\nRecommended deployment model:\n\n- keep ZenNotes behind a reverse proxy, VPN, or private network gate\n- do not expose the raw Go server directly to the public internet unless you understand the tradeoffs\n\n### Choosing a different host folder\n\nYou can mount a different host content root:\n\n```bash\nCONTENT_ROOT=\"$HOME\u002FLibrary\u002FMobile Documents\u002Fcom~apple~CloudDocs\" make up\n```\n\nThat works for paths with spaces too.\n\nUseful variables:\n\n- `CONTENT_ROOT`: host folder used as the live vault root\n- `DATA`: host directory used for persisted server config\n- `PORT`: published host port\n- `IMAGE`: Docker image tag\n- `ALLOW_INSECURE_NOAUTH`: disable the default auth requirement\n\n### Docker browse model\n\nImportant limitation:\n\n- the Docker container can only browse folders that are mounted into it\n- it cannot browse your entire host filesystem\n- by default, the picker is scoped to the mounted content root unless you explicitly relax it\n\nSo if you want to browse an Obsidian vault, iCloud Drive, or another directory from the web picker, that directory needs to be mounted into the container first.\n\n### Relevant container env vars\n\nThe current compose\u002Fruntime flow supports:\n\n- `ZENNOTES_BIND`\n- `ZENNOTES_CONFIG_PATH`\n- `ZENNOTES_DEFAULT_VAULT_PATH`\n- `ZENNOTES_BROWSE_ROOTS`\n- `ZENNOTES_VAULT_PATH`\n\nBehavior notes:\n\n- `ZENNOTES_VAULT_PATH` hard-locks the server to a specific vault path\n- `ZENNOTES_DEFAULT_VAULT_PATH` sets the starting vault when no saved selection exists\n- `ZENNOTES_BROWSE_ROOTS` limits what the web picker can browse\n- `ZENNOTES_ALLOWED_ORIGINS` restricts which browser origins can connect\n- `ZENNOTES_ALLOW_UNSCOPED_BROWSE=1` removes browse-root enforcement\n- `ZENNOTES_ALLOW_INSECURE_NOAUTH=1` disables the default auth guardrail\n\n## Web vault picker\n\nThe self-hosted web build now includes a server-backed vault chooser.\n\n- it browses folders on the server, not the browser machine\n- it only browses configured allowed roots by default\n- it starts from sensible locations instead of requiring blind path typing\n- it supports a simpler folder-picker flow for choosing the active vault\n- on macOS-hosted servers, common shortcuts like iCloud Drive are supported when available\n\nIf you start the server with `ZENNOTES_VAULT_PATH`, manual vault switching is intentionally disabled.\n\nIf auth is enabled, the browser asks for the bootstrap token once and then switches to a secure session cookie. ZenNotes no longer relies on auth tokens in browser URLs or local storage.\n\n## MCP integration\n\nZenNotes ships a dedicated MCP server and desktop install flows for:\n\n- Claude Code\n- Claude Desktop\n- Codex\n\nThe desktop app can:\n\n- detect whether the ZenNotes MCP entry is installed\n- install or uninstall it for each supported client\n- show the exact runtime used to launch the server\n- edit the server's default instructions from Settings\n\nThe MCP server exposes vault operations such as:\n\n- reading notes\n- creating notes\n- moving notes\n- appending to notes\n- listing notes\n- searching vault text\n- listing files\u002Fassets\n- toggling tasks\n\n## Building and packaging desktop releases\n\n### Build everything\n\n```bash\nnpm run build:prod\n```\n\n### Desktop package scripts\n\n```bash\nnpm run pack\nnpm run dist:mac\nnpm run dist:win\nnpm run dist:linux\n```\n\n### Signed macOS releases\n\nPublic macOS releases are wired for hardened runtime signing and notarization.\n\nThe GitHub Actions release workflow expects:\n\n- `MACOS_CERTIFICATE_P12`\n- `MACOS_CERTIFICATE_PASSWORD`\n- `APPLE_ID`\n- `APPLE_APP_SPECIFIC_PASSWORD`\n- `APPLE_TEAM_ID`\n\nOptional Windows signing can be supplied with:\n\n- `WINDOWS_CERTIFICATE_P12`\n- `WINDOWS_CERTIFICATE_PASSWORD`\n\nTagged releases fail the macOS release job if the required Apple signing or notarization secrets are missing. That prevents accidentally shipping an unsigned public mac build.\n\n## Current status\n\nZenNotes is actively evolving. The desktop app is the more mature runtime today, while the self-hosted web\u002Fserver path is being brought into parity through the shared monorepo core.\n\nThat means:\n\n- many features are shared already\n- some platform-specific behavior still lives in the shell layers\n- the README will keep evolving as desktop, web, and self-hosted flows converge further\n\n## License\n\nMIT\n","ZenNotes 是一个以键盘操作为主的本地 Markdown 笔记应用，支持 Vim 操作、图表和 MCP 集成。其核心功能包括使用普通 Markdown 文件存储笔记、Vim 友好的编辑方式、多模式（编辑、拆分、预览）工作流、任务管理、标签、归档\u002F回收站以及数学公式和图表的直接渲染。此外，ZenNotes 提供了 Electron 构建的桌面应用版本及自托管 Web 应用版本，并计划推出基于相同技术栈的托管部署模式。它适用于需要高效编写和组织 Markdown 笔记且偏好键盘导航的用户场景，特别适合那些希望在没有数据库的情况下保持笔记简洁并能快速访问和编辑的人士。",2,"2026-06-11 02:43:42","CREATED_QUERY"]