ZenNotes
ZenNotes manual
Choose an app, understand your sync options, and find the commands and settings you need. The run guides also cover source development and self-hosted installations.
ZenNotes keeps your notes as plain .md files in a vault you
own. Desktop, mobile, and the self-hosted browser app share an editor
core, with platform-specific features in each app. The Go terminal app
works with the same files through its own interface. ZenNotes Cloud
provides hosted sync, backups, and publishing for the desktop and mobile
apps.
This website guide complements the manual bundled with your installed version. Press :h or open Help from the sidebar footer to browse the in-app manual. The shortcut and settings reference below describes the shared editor; see the TUI guide for terminal-specific controls.
Checking whether ZenNotes can do something specific? Jump to the Feature index, a scannable list of every feature with the fastest way to reach it. Press Cmd/Ctrl+F to search this page.
Choose where your files live and which interface you want to use. Local notes do not require a Cloud account or subscription.
The macOS, Windows, and Linux app opens a local Markdown vault, optionally syncs it through ZenNotes Cloud, or connects to a self-hosted Go server. Native windows, the updater, and platform integrations belong to the desktop app.
The mobile apps use the shared editor with native storage and mobile controls. ZenNotes Cloud syncs linked local vaults across desktop and mobile. iOS also supports iCloud; Android can open a user-selected folder through its system folder picker. Platform capabilities differ, so desktop integrations are not available everywhere.
Run ZenNotes/znserver, open its URL, and sign in with that server's token. The browser edits files on the server. The server is a separate product from ZenNotes Cloud and does not use your zennotes.org account. A cached browser shell does not provide offline note editing; note requests need the server.
The Go zn binary runs without the desktop app, Node.js, or a Cloud account. Use it with a local vault or a self-hosted server. It has its own editor and supported feature set; it does not connect directly to ZenNotes Cloud or support desktop CSS themes, Atlas, or Workflows. Run zn --help for commands and :help inside zn tui.
Connect from Settings → Cloud in a supported desktop or mobile app and link that local vault. The website manages your account, plan, vaults, and exports. Signing in to zennotes.org does not open a private-vault browser editor. Use the desktop or mobile apps to edit Cloud-synced notes.
When ZenNotes Cloud can't finish something, the app's status bar and Settings → Cloud say what happened and what you can do, in plain words: Can't reach Cloud when the device is offline or Cloud is unreachable, or Signed out of Cloud when the device was removed from your account on this website. Your notes stay on the device either way. Under the message, Details holds the technical line (Cloud's answer, its HTTP status and code); Copy details puts it on the clipboard, and Report an Issue opens the ZenNotes issue tracker on GitHub so you can paste it into a report. The status bar shows these even when you have turned it off under Settings → Appearance → Chrome.
When Cloud refuses one file, the rest of the vault keeps syncing, and Settings → Cloud lists the file, what to do about it, and Cloud's answer under Details. Nothing is lost. Usually it is a file ZenNotes keeps for itself under .zennotes, and there is nothing to change on your side: the run counts as synced, the status bar reads Synced as usual (its tooltip adds 1 file stays on this device), and sync offers the file to Cloud again once a day, so it goes up by itself once Cloud takes it; if it keeps coming back, copy the details and choose Report an Issue. If it is one of your notes or attachments, it waits for you: the status bar reads 1 file stays on this device until you fix it, even when you have turned the status bar off. Cloud did not accept its name or location, most often because the path is longer than the 1,024 characters Cloud takes: give it a shorter name or move it to a folder nearer the top of the vault, and it syncs under the new path. A note you moved or renamed there stays in Cloud under its old name until then, so your other devices keep it.
Publishing creates a share page for a selected note. Its viewer is for reading published content, not editing your private vault. Publishing a note and syncing a vault are separate actions; syncing alone does not create a public share link. A published note can have up to 50 attachments and 100 MB in total, such as images and PDFs, each up to 10 MB; a note over a limit says so before anything uploads. Versions before ZenNotes 2.66.0, iPhone 1.22.0 and Android 1.1.36 publish up to 20 attachments.
End-to-end encryption keeps a Cloud vault unreadable to ZenNotes Cloud. Your devices encrypt its notes, attachments, file and folder names, and the vault's own name before anything is uploaded, with a key only you hold. It is in beta: Settings → Cloud shows it once it is available for your account, and you turn it on for each vault.
Update every device first: ZenNotes 2.67.0 or newer on your computer, 1.23.0 or newer on iPhone and iPad, 1.1.37 or newer on Android.
Settings → Cloud → End-to-end encryption → Set up encryption. Pick a passphrase of at least 12 characters; four or more unrelated words work well. It is not your account password, and it never leaves your devices.
ZenNotes shows 24 words. Keep them somewhere safe, such as a password manager or paper, tick that you saved them, and type back the three words it asks for. The passphrase or the recovery key unlocks encryption. ZenNotes never receives either one and cannot reset them.
For a new vault, tick End-to-end encrypt this vault when you create it. For a vault already on Cloud, choose Encrypt this vault: ZenNotes makes a new encrypted vault with the same name, uploads this device's copy, then deletes the readable Cloud copy with its version history and backups. Download a backup first if you want to keep one.
Your other devices stop syncing the old vault. On each one, unlock encryption once with the passphrase or the recovery key, then open the encrypted vault from Settings → Cloud.
zennotes.org/security lists everything ZenNotes can and cannot see.
Unlock with the 24 recovery words, then choose Change passphrase. New recovery key replaces the words if you think someone saw them.
Nobody can decrypt the Cloud copy, ZenNotes included. The notes on your devices are untouched: make a new encrypted vault and upload them again.
Your email and plan, how many files a vault holds, their sizes, and when they change. Not their names, their content, or the vault's name.
Settings → Cloud → Lock this device forgets the key here. A locked device keeps its notes but does not sync the encrypted vault until you unlock it.
Publishing a note from an encrypted vault makes a readable public copy until you unpublish it.
The website cannot export an encrypted vault as a ZIP. In the desktop app, Save archive under Backups in Settings → Cloud saves a readable archive; the phone apps send you there.
For everyday use, download an app or install the terminal tool. For a browser connected to your own server, start with Docker. Source commands below name the repository they belong to.
Install a packaged release for everyday use. The commands below are for developing the Electron desktop app from the ZenNotes/zennotes repository.
git clone https://github.com/ZenNotes/zennotes.git
cd zennotes
npm ci
npm run dev:desktop
make desktop
The fastest way to self-host in the browser. Pull the prebuilt multi-arch image from Docker Hub, with no git checkout or local build required.
TOKEN=$(openssl rand -hex 32)
mkdir -p "$HOME/Documents/MyVault" "$HOME/zennotes-data"
docker run -d --user "$(id -u):$(id -g)" --name zennotes -p 127.0.0.1:7878:7878 -e ZENNOTES_AUTH_TOKEN="$TOKEN" -v "$HOME/Documents/MyVault:/workspace" -v "$HOME/zennotes-data:/data" --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges adibhanna/zennotes:latest
echo "$TOKEN"
open http://localhost:7878
Run these commands from a ZenNotes/zennotes checkout. Its Compose file and Makefile pull the published server image and generate the auth token. The Go server source itself lives in ZenNotes/znserver.
CONTENT_ROOT="$HOME/Documents/MyVault" make up
cat data/auth-token
open http://localhost:7878
make down
make logs
make rebuild
Run these commands from a ZenNotes/zennotes checkout with Node.js 22+ and npm. For normal self-hosted use, prefer the Docker flow above.
npm ci
npm run dev:server
npm run dev:web
make web-stack
Best if you want the native desktop app, but the vault itself lives on another machine running the ZenNotes server.
Open ZenNotes
Settings -> Vault -> Quick Connect…
Choose the vault folder on the server
The shortest path from install to a working vault.
A vault is just a folder of Markdown files. ZenNotes reads it directly, keeps everything file-based, and never hides your notes behind a database. That can be a local folder on desktop or a host-mounted folder served remotely through Docker.
A cover is a wide banner image across the top of a note. Press Space l c in Vim mode, run Add Cover… from the command palette, or type :cover to open the cover picker. Type to search it, move with the arrow keys and press Enter to pick a gradient, a photograph from the gallery (public-domain works from The Met and NASA), or an image already in the vault. Upload image… takes a file from disk, and an image you paste (⌘V / Ctrl+V) or drop anywhere in the picker becomes the cover; paste an https link into the search field to use a picture from the web, or press Tab for the Unsplash tab and its free photos (see the next guide). Gradients, gallery photos and uploads are copied into the vault’s assets/ folder like a pasted image, so the cover works offline, on a self-hosted server and through Cloud sync, end-to-end encrypted vaults included. Hover the cover for Change cover, Reposition and Remove, or drop an image straight onto it. Reposition (also Reposition Cover in the palette and :cover reposition) lets you drag the picture up or down, or move it with ↑/↓ (j/k in Vim mode, Shift for small steps); Enter keeps the new position and Escape puts the old one back. The cover is plain frontmatter, banner: "![[assets/photo.jpg]]" with the focal point in banner_y (0 is the top edge, 1 the bottom), the keys Obsidian’s banner plugins read, so a shared vault shows the same banner there; a cover: image, or one written as a plain [[link]], shows too. In Edit and Split, a cover’s frontmatter lines fold into one muted line in the note’s properties, such as cover · lisbon.jpg or cover · Unsplash photo by Jane Doe, since the cover above already shows the picture. The other properties stay as they are. Move the cursor onto that line (the arrow keys, or j/k in Vim mode) or click it, and the raw banner, banner_y, banner_credit and banner_credit_url lines open for editing; they fold again when the cursor leaves. The file itself never changes, so copying, searching and undo work on the lines as written. With Live Preview off, or covers hidden in Settings, the lines show in full. The Assets view counts a cover image as used, renaming or moving the image updates the note, and Undo takes back a cover change made in the editor. Settings → Typography → Note covers decides whether the cover scrolls away with the text, stays pinned above the editor and Read view, or is hidden. A published note’s public page shows its cover too, and so does Quick Look when you press Space on a note in Finder on macOS: both draw it read-only at the note’s focal point. Quick Look follows the Hidden setting and leaves out a cover from the web, since a preview never goes online.
The cover picker has a second tab, Unsplash, that searches Unsplash’s free photos with an access key of your own. The first time, the tab says how to get one: at unsplash.com/developers, open Your apps, create a New Application (a free Unsplash account is enough) and copy its Access Key; then press Enter on Open Settings and paste the key into Settings → Typography → Covers → Unsplash access key (Set Unsplash Access Key… in the command palette goes there too). Save checks the key with one request to Unsplash and keeps it unless Unsplash refuses it, Test asks again and says how many of the hour’s requests are left, and Clear removes it. The desktop app keeps the key in your system’s secure storage and the web client in your browser, never in config.toml or the vault, and sends it only to api.unsplash.com: searches go from your machine straight to Unsplash, and zennotes.org takes no part. A new Unsplash app allows 50 requests an hour until Unsplash approves it for production; when they run out the tab says so, and if Unsplash stops accepting the key it offers Change key. Press Tab in the picker to switch between Covers and Unsplash (what you typed comes along), press Space l u in Vim mode, run Add Cover from Unsplash… from the command palette, or type :cover unsplash mountains to open the tab on a search. Photos appear as you type; move with the arrow keys (or Ctrl+N/P, Ctrl+J/K) and press Enter to make the selected one the cover. The line under the grid credits the selected photo’s photographer, with links to their profile and to Unsplash. Unsplash’s rules keep its photos on Unsplash, so unlike a gradient or a gallery photo the picture is not copied into assets/: the note links to it, banner: "https://images.unsplash.com/…", with the credit on the two lines under it, banner_credit (the photographer) and banner_credit_url (their Unsplash profile). In the editor these three lines fold into one, cover · Unsplash photo by …, until the cursor moves onto it. Hover the cover to see Photo by … on Unsplash with both links; a published note’s page always shows it. The picture needs a connection to load. One you have seen before usually still shows offline; otherwise the cover says it could not load the picture from images.unsplash.com. To keep a photo for offline use, download it from unsplash.com and drop it on the picker. The Covers tab never goes online. Choosing another cover or removing this one takes the credit away with it.
The Gallery shows one folder’s notes as a grid of cards: each card leads with the note’s cover (an image in the vault, an Unsplash photo or a gradient, cropped to fill the card at the cover’s focal point), then its title and date. A note without a cover gets a quiet card with the first letter of its title. Right-click a folder in the sidebar and choose Open as Gallery, run Open Folder Gallery from the command palette, press Space G in Vim mode, or type :gallery. The palette, Space G and a bare :gallery open the folder under the sidebar cursor while the sidebar has focus, and the open note’s folder otherwise; :gallery Projects/Website names a folder (a path in the vault, a folder in your notes, or a system folder such as archive). Each folder opens as a tab of its own, named after the folder. The header shows how many notes there are, a Sort menu (Updated, the default, puts the last edited first; Created puts the newest first; Title goes A to Z), and an Include subfolders switch, off by default, that adds the notes in the folder’s subfolders. Both choices apply to every Gallery and are kept in config.toml as gallery_sort and gallery_include_subfolders under [view]. A database’s record pages and drawings are left out. In Vim mode h / j / k / l move across the grid, gg / G jump to the first and last card, Enter or o opens the note and / filters the cards by title; with Vim mode off the arrow keys move, Enter opens and you click into the filter to type. Escape clears the filter. Click a card to open its note; Ctrl+O comes back to the Gallery, on the card you opened. Only the cards on screen are drawn, and a note is read for its cover only when its card scrolls into view, so a folder of thousands of notes opens at once. It works the same in a vault on a self-hosted server and in the web app, and at phone width it keeps two columns.
A vault is named after its folder, which is fine until several vaults are all called docs, one per project repo. Rename the vault without touching the folder: Rename Vault… in the command palette (:vault_rename on the ex line), the same entry in the sidebar's vault menu (click the vault name at the top of the sidebar), or the Vault name field under Settings → Vault → Location. The name shows in the sidebar header, the vault switcher (Space v), the title bar and zn vault list; the folder keeps its name on disk, and clearing the field goes back to it. It is saved in the vault's own .zennotes/vault.json as displayName, so it travels with the folder to every machine that opens it and appears in the switcher once the vault has been opened there. A temporary folder session and a remote workspace do not offer it: the first writes nothing into its folder, the second's settings belong to its server.
Since 2.51.0 a note's creation date is app-owned metadata stored beside it under .zennotes/note-metadata, moved, renamed and deleted with the note by the desktop, the CLI and the MCP server, so it survives syncs, copies and filesystems that drop birth times. Keep the .zennotes folder with the vault in backups; Cloud sync carries it as vault content.
The sidebar is your navigator, the note list is your current folder or attachments view, and the editor pane is where tabs, splits, preview, and focused writing happen.
Quick Notes are for fast capture, Inbox is active work, Archive is cold storage, and Trash is recoverable deletion. Archive and Trash open as dedicated main-pane lists so the sidebar stays singular; Quick Notes stays foldable in the sidebar and can also open its own list tab from the context menu.
Search notes, search vault text, and open the command palette from their configured shortcuts. Use Vim mode for ex commands, pane motion, hint mode, leader hints, link-following, and keyboard-opened context menus. Once a picker is open, Arrow keys and Ctrl+N / Ctrl+P both move through results. When note search turns up nothing, Shift+Enter opens a small New note form with your search as the name; pick a folder and tags if you like, press Enter, and the note opens in the editor. A search that comes up empty is two keystrokes from becoming the note.
Type / in the editor to open a slash menu for headings, lists, callouts, code blocks, dividers, tables, links, images, and more. Type @ to insert date shortcuts like Today, Yesterday, and Tomorrow as Markdown-friendly ISO dates, to pick any other day from a calendar (@date), or to link a matching note.
Folder icons can be changed from the folder context menu, sidebar arrows can be hidden, and Quick Notes can use either timestamp titles, date titles, or a custom prefix.
Export Note as PDF… uses the rendered Markdown note, not raw text. On desktop it saves directly; in the browser it opens a print-friendly white paper view so you can Save as PDF.
Open Help from the sidebar footer or with :help to browse shortcuts, commands, panel behavior, Vim flows, and settings in one place.
Run Generate Demo Tour Notes from the command palette to add a guided set of demo notes under inbox/demo: about twenty notes covering writing, diagrams, tasks and boards, templates, workflows, Cloud, and the CLI, with a sample Excalidraw drawing, a sample database, and an image to try them on. Run Remove Demo Tour Notes to clear them later.
ZenNotes restores the last open tabs, splits, built-in views, and sidebar layout for each vault, and remembers the main window size, position, and maximized state between launches. Remote vault connections can also be saved for quick switching later.
A single scannable index of every user-facing capability in ZenNotes, grouped by domain. Each row lists the fastest way to reach a feature (a shortcut, ex command, command-palette entry, slash command, Settings path, or CLI command), so you can confirm a feature exists and use it without reading prose.
Press Cmd+F (macOS) or Ctrl+F (Windows/Linux) to search this page for a feature name, a shortcut, or an ex command. Each group below covers one domain; jump to the matching group, then scan its table.
Mod means Cmd on macOS and Ctrl on Windows/Linux. Bindings shown are defaults: every shortcut, Vim binding, and sequence is remappable in Settings → Keymap. Leader bindings (Space prefix) and ex commands (typed after :) require Vim mode; the equivalent command-palette entry works in any mode.
Many features have more than one access path. Where that is true, the row lists all of them: shortcut and ex command and palette entry. Use whichever fits your current context.
Six domains. Jump to the one that matches what you are looking for.
Markdown editor and view modes, live preview, slash and @ menus, wikilinks, folding, math, diagrams, callouts, tables, code blocks, comments, find & replace, and formatting.
Editing
Sidebar, note list, panels, tabs, splits, reference panes, palettes, zen mode, theme switching, floating windows, and session persistence.
Workspace
Inbox, Archive, Trash, Quick Notes, Tasks, Tags, templates, daily and weekly notes, folders, assets, and all create/rename/move/duplicate/delete operations.
Notes
Global shortcuts, the Vim leader and which-key system, pane motions, ex commands, list navigation, and command-palette categories.
Keys
Themes, typography, editor behavior, vault location, daily/weekly/monthly notes, system folder labels, and the keymap editor.
Settings
zn CLI, MCP server and tools, Raycast extension, the Go server, remote vaults, PDF export, and app updates.
Integrations
Turn any .csv into a Notion-style database: an editable Table and a grouped Board over the same data, typed fields including note links, select options discovered live from a folder or tag, sort and filter, records as Markdown pages, and a vim-driven grid.
Databases
Switch how the active note is shown. Each mode has a shortcut, an ex command, and a palette entry.
Insert structure and resolve links without leaving the keyboard.
Markdown rendering features. All are GFM-based and theme-aware; diagrams expand to a pan/zoom modal.
Show, hide, and arrange the chrome around the editor.
Multi-pane editing. Split and pane commands work via Vim Ctrl+W, ex commands, and the palette.
Fast finders. Each has a shortcut and a Vim leader binding.
Special views that gather notes and tasks across the vault.
Annotate inline task lines, or make a whole note a task; tasks are parsed across all notes.
Any .csv in the vault is a full database, with zero new dependencies. Create one with 'New Database' in the command palette or by right-clicking a folder → New database.
Mode-independent shortcuts. All remappable in Settings → Keymap.
Vim mode only. Press Space, then the next key; enable which-key hints in Settings → Editor to see options.
Active when a list or panel (not the editor) has focus. With Vim mode off the letters are off, and the arrows (→ opens, ← goes back), Enter, Esc, Home / End, Page Up / Page Down and Shift+F10 do the work.
Type : in Vim normal mode, then a command. Tab cycles completions in a wildmenu. Every palette command is also reachable as an ex command (kebab-case to underscores).
Open with Mod+, then choose a tab.
Install from Settings → CLI, then run zn in any terminal. Override the target vault with ZENNOTES_VAULT; most commands accept --json.
Connect AI agents, Raycast, and remote servers. MCP and Raycast are set up in Settings → MCP and Settings → CLI.
How ZenNotes thinks about files, panes, leaders, and keyboard control.
A system-wide hotkey (Cmd/Ctrl+Shift+Space by default, configurable under Settings → Editor) opens a small always-on-top capture window over any app. You type in one place: the first line becomes the note title, the rest is the body. Mod+Enter saves into Quick Notes and hides it, Mod+N saves and starts a fresh note without hiding, and Mod+P opens an existing note to edit. Editing the first line of a Quick note renames it in place instead of creating a duplicate, and the window can be dragged anywhere.
On macOS, choose Share → ZenNotes in Safari or any app with a Share menu to save the page you are on, the text you selected, or both, into Quick Notes or the place you pick under Settings → Vault → Notes → Default shares location. The sheet takes an optional note line and, when you use more than one vault, the vault it goes to (⌘1 to ⌘9 pick one); Return saves and Escape cancels. A page becomes a note named after the page, with the selection quoted and a link back; text on its own is named from its first line. With ZenNotes closed, the share waits and is filed the next time you open it.
ZenNotes edits Markdown on disk. Rename, move, archive, restore, and floating-window operations all work on the underlying files, not an internal copy.
Each editor pane can hold multiple tabs. Split the current tab right or down, move between panes with motions, switch the active note between Edit, Split, and Preview, and use the buffer switcher or :buffers when tabs are hidden. The active tab has a full keyboard context menu: Close Others, Close Right, Pin, Pin as Reference, Open in Floating Window, and Reveal in Finder. Each note keeps its own undo history while the app is open: switch tabs, or close a note and open it again, and u / Mod+Z (and redo) still walk through the edits you made to it. Renaming or moving the note you are editing keeps its caret, scroll position and undo history too. If the note was changed somewhere else in the meantime (another pane, sync, an external editor), it starts a clean history, because the old undo steps would no longer fit the text. The same happens the moment a sync tool, a script or another editor changes the file while you are looking at it: the new text appears in place, the caret stays, and Undo starts over instead of undoing your earlier typing underneath text that arrived from outside. Another pane typing into the same note leaves the history alone. On the desktop app you can also keep undo history after quitting, the way Vim's undofile does: turn on Settings → Editor → Keep undo history after quitting (or :set undofile in Vim mode, or the command palette). It is off by default because the history contains text you deleted; it is stored with the app on that computer, never in your vault, histories nobody returns to expire after 90 days, and turning the setting off erases them all. It travels in config.toml as persist_undo_history under [editor].
Settings → Editor → Default view mode chooses what a note opens in before you have picked a mode for it: Edit to write, Preview to read, Split for both. Each note still remembers the mode you last used on it, and the choice travels with your portable config.toml as default_view_mode. Switching from Edit into Preview also opens the reading view at the line your cursor was on, so switching to Preview to read what you just wrote lands exactly there. Coming back follows where you read: if you only peeked and your cursor line is still in view, the cursor stays put; if you scrolled on to another part of the note, Edit or Split opens with the cursor on the section you were reading (Split also re-aligns the reading view beside it). To edit a specific passage, double-click it in Preview and the editor opens right there; the “Edit this block” button on an image embed does the same.
The Connections, Outline, Comments, Calendar and Timeline panels stay as you set them while you move between notes. If you would rather each note kept its own, turn off Settings → Editor → Keep panels when switching notes, or run Remember Panels per Note from the command palette. A note then comes back with the panels you left it with, after a restart too (the memory is saved with your tabs and layout, never in the note), and a note you have not opened yet starts with none. With the automatic calendar on, a daily or weekly note whose calendar you closed stays closed when you return to it. The setting travels with your portable config.toml as keep_panels_across_notes under [view]. The note always keeps a readable width: in a narrow pane (a split, a small window) the panels first shrink, and if they still do not fit, the ones you opened longest ago are tucked into a slim rail at the pane's right edge. They stay open; click one in the rail, or press its usual shortcut, to bring it forward.
The Timeline is a right-hand panel beside your note that lays every open task in the vault with a date down one line, in date order. Open it with Mod+7, Space n in Vim mode, :timeline, Toggle Timeline in the command palette, or its button in the note header. A task’s date is its due: date, or for a task in a daily note, that note’s date, the same as the calendars. Overdue tasks sit on top in red, each with how many days late it is; Today follows with the accent ring, then one node for each later day that has work, and a run of empty days in between folds into one “N quiet days” line. Which tasks count is the Tasks view’s rule: open Today and Upcoming work, [/] in progress included; done, cancelled, forwarded and @waiting tasks keep to their own groups in Tasks. The header counts what is on the rail (“9 open · 2 overdue”), and the switch under it reaches 2 weeks ahead (the default), a month, or All; tasks past the range are counted at the bottom, and clicking that count shows them all. The choice is kept in config.toml as timeline_range under [view]. The filter takes the Tasks filter syntax: words, #tag, !high, @key:value. Tag a task #milestone to make it a milestone: its day draws as a diamond marked “· milestone”, its row stands out, and it says how many open tasks are due before it, counted from the previous milestone (or from the top of the rail for the first one, overdue included), so each task counts toward exactly one milestone. Nowhere else treats #milestone as special. Undated tasks stay off the rail; “N undated in Tasks” at the bottom opens the Tasks view, where they are listed. Click a row (or press Enter) to open the note at the task’s line, tick its box to check it off (it leaves the rail), right-click for the task menu, and rest the pointer on it to read the note. In Vim mode j / k move, gg / G jump to the ends, x ticks, m opens the task menu and / focuses the filter; with Vim mode off the arrows, Home / End, Enter and Escape work. Escape (or ←) hands the keyboard back to the note. Like the other panels it resizes from its left edge, tucks into the rail in a narrow pane, and stays open as you move between notes.
ZenNotes treats context menus as keyboard-reachable UI. Use the configured context-menu binding on the selected sidebar or note-list row. In the editor with Vim mode on, select text and press m (or Shift+F10) to open the text menu with commenting first; Shift+F10 / the system Context Menu key still opens the active tab menu when no text is selected. With Vim mode off, Shift+F10 or the Context Menu key opens the editor’s right-click menu at the cursor, with or without a selection, on macOS as on Windows and Linux.
When no note is open (outside Zen mode), ZenNotes shows a light home view instead of a blank pane: a greeting, quick-create actions (new note, database, drawing, plus daily and weekly notes when those are enabled in Settings), your most recently edited notes, your Favorites, and the tasks due today or overdue, with an overdue count. The Favorites section sits right after Recent and mirrors the sidebar’s list in the same order: a favorited note opens in place, a favorited folder opens that folder in the note list (bringing the sidebar back if it was hidden), and the section stays out of the way until you favorite something. Favorite a note from the sidebar row’s context menu, `Space l s`, or the command palette’s “Add Note to Favorites” (on the phones, the same entry sits in the ••• sheet and in the long-press note menu). Click a note or task to open it, tick a checkbox to complete a task in place, and use ↑/↓ (or j/k in Vim mode) then Enter to move and open from the keyboard.
Workspace restore is saved per vault, while the window frame is global. Reopening ZenNotes brings back your pane layout, open buffers, built-in views, and the last window bounds.
If Leader key hints are enabled, pressing Leader opens a which-key style panel that shows the next available actions. Settings let you pick a timed hint or a sticky leader overlay that stays open until you dismiss it.
Tasks scans every note for checkboxes and groups the open ones by when they are due: Today (due today or overdue), Upcoming, and No due date, then Waiting, Forwarded, Done, and Cancelled. A task written in a daily note counts as due on that note’s date. Inside each group the list keeps the notes’ line order, or puts high priority first when its Order menu says Priority (s in Vim mode). Tags lets you browse notes by tag, down to the tagged blocks inside each note. Archive gives you cold storage. Trash gives you recovery without turning the left rail into a second browser.
Open a tag (click it in the sidebar or in a note, or run :tag idea) and the Tags view lists each matching note with its tagged blocks under the title: every list item, paragraph, quote, or table row inside the note that carries the tag. Several unrelated ideas jotted into one note show up one by one instead of as one note you have to read through. A tagged list item brings its nested items along, and a tag on a heading tags its whole section: the row shows the heading with the first lines under it. Enter, o, or a click on a block opens the note at that line and highlights it; Enter on the note row opens the note at the top as before. The header counts both (“3 notes · 5 blocks”). The filter box narrows to the blocks whose text matches what you type, and keeps every block of a note whose title matches. With Vim mode on, } and { hop from note to note past the blocks. Tags in frontmatter tag the whole note, so a note tagged only there stays a plain row, and a #tag inside code is never a tag. A block you type into an open note lists right away. Search notes shows the same blocks: type #idea and each matching note lists up to two of its tagged blocks under it, then a “+N more tagged blocks” row that opens the rest in the Tags view; Enter on a block opens the note at that line. Words after the tag narrow the blocks to those containing them (marked in each block), and a note found by such a word deep in its body is listed too, while a note that matched only by its title stays a plain row. With several tags (#idea #later) notes still carry all of them, and the blocks carrying all of them come first. Without a #tag the palette lists notes as always. If the extra rows feel cluttered, turn off Settings → Editor → Search → Show tagged blocks in note search (tagged_blocks under [search] in config.toml).
Besides inline - [ ] checkboxes, a whole note can itself be a task: give its frontmatter a task tag (tags: [task]) and its metadata lives in frontmatter, including status (open / in-progress / done), priority (high / normal / low), due and scheduled dates, plus any tags, while the body holds free-form detail or sub-checkboxes. These task files appear in the Tasks List, Calendar, and Kanban right alongside inline tasks, so both styles live in one vault. It follows the TaskNotes convention, so a vault stays interoperable with TaskForge and Obsidian. Quick-add one from the command palette (“New Task”, or “New Task in Folder…” to choose where it lands), the “+ New task” button in the Tasks header, the a key in Vim mode (on the Tasks calendar with daily notes on, a adds a task to the selected day instead), or the :newtask / :task command; :newtask Projects/Website drops it straight into a folder so multiple projects stay organized. New task files default to your configured tasks location (Settings → Vault → Notes → Default tasks location): your primary notes area unless you pick the active note’s folder or a specific folder, and a specific folder lives inside the primary notes area, so Tasks means inbox/Tasks/ in Inbox mode and Tasks/ in Vault root mode. The folder-picking options override it per task. Checking a task file off rewrites its frontmatter (status: done and a completedDate) rather than a checkbox character, and rescheduling from the calendar or changing its Kanban column updates the matching frontmatter field.
A reading list is a checklist, not a to-do. Add tasks: false (or off) to a note’s frontmatter and its checkboxes stay checkboxes: they render and toggle exactly as before, but stop feeding the Tasks list, the boards, the calendars, zn task list, and the MCP tools. On a #task note, tasks: note keeps the note itself on the board while silencing its internal checklist, so a project note can be one card instead of twenty. To collect tasks from a few folders only, such as a single Tasks folder, right-click each one in the sidebar and choose “Use as Task Folder”: once any Task folder is set, checkboxes everywhere else stay plain checkboxes. To retire a whole folder instead (a media backlog, a reference library), choose “Exclude from Tasks”, which also works inside a Task folder. Both lists live under Settings → Tasks and in the vault’s own settings, so the desktop app, the self-hosted web app, the CLI, and the MCP tools agree. In Settings, the field under each list offers the vault’s folders: type to narrow them and pick one with Enter, or type the path of a folder that does not exist yet. When you do want to see past them, zn task list --include-excluded and the MCP list_tasks includeExcluded flag list everything.
Press ⌘L (Ctrl+L on Windows and Linux) in the editor to mark the task under the cursor done, or to turn the current line into a checkbox and toggle it on repeat: plain text becomes - [ ] text, an existing bullet or numbered item keeps its marker (* note becomes * [ ] note), and pressing again flips [ ] to [x] and back. An in-progress [/] checks off to [x]; forwarded [>] and cancelled [-] lines are left alone, since those states have their own commands. It applies to every line of a multi-line selection and works with Vim mode on or off. In Vim it works from normal, insert, and visual mode and leaves you in the mode you were in, so Vjj then ⌘L checks off three tasks and one u undoes them. Rebind it as editor.toggleCheckbox (Settings → Keymaps or [keymaps] in config.toml); it is also in the command palette as Toggle Checkbox.
Add @repeat: to a task and checking it off schedules the next one: - [ ] Water the plants @repeat:weekly due:2026-11-01. The rules are daily, weekdays, weekly, monthly and yearly; 2d, 3w, 6m or 1y for every so many days, weeks, months or years; weekdays like mon/thu; and after-3d (any interval) to count from the day you finish instead of the due date. Check it off with ⌘L, a click on its checkbox, x in the Tasks views or a drop into Done, and the next occurrence is written right above it with the next date in due:, while the finished line stays below as the record, without @repeat, so unchecking it never makes a second copy. Its subtasks repeat too, every checkbox open again, and the record cancels ([-]) the ones you left open, so only the fresh copies stay on your lists; subtasks you select along with the task (Vjj then ⌘L) are checked off instead. The next date counts from the due date (or, without one, the daily note’s date, then today) and is never today or earlier: a daily task done three days late comes back tomorrow, not as three overdue copies. monthly from the 31st lands on the last day of shorter months. Press r in the Tasks views (or Repeat… in the right-click menu, or :repeat weekly in a note) to set or stop it; Skip this time in the menu schedules the next one and records this one as cancelled. Typing an x into the brackets by hand is just text and does not repeat. Whole-note task files do not repeat yet.
Add @remind: to a task with a due date and the desktop app shows a notification: @remind:9am (or 930am, 1730, 17h30) at that time on the due date, @remind:1d the day before at your reminder time (09:00 unless changed in Settings → Tasks), @remind:2d-6pm two days before at 6 PM. A daily note’s tasks remind on the note’s date. Click the notification to open the task. Press R in the Tasks views (or Remind… in the right-click menu, or :remind 9am in a note) to set or remove it. Reminders fire from the desktop app while it runs, the window hidden in the tray included; after ZenNotes was quit, the next launch shows what came due in the last 24 hours once, as one notification. A recurring task carries its reminder to each new occurrence.
Every command in the command palette can take a key of its own, from Move Note to Trash to Toggle Word Wrap; all of them start unbound. In the palette, highlight a command and press Alt+Enter (Option+Enter on macOS): a recorder opens over the palette, you press the key, Enter saves and Escape goes back to the same row, which now shows its key. Or open Settings → Keymap, where the Commands group lists every command with its category and id (filter by title, category, keywords or id; Settings search finds a command by its title too), and use Change…, Unbind and Reset as on any other row. A command’s key is a chord with Ctrl, Alt or Cmd, such as Mod+Backspace, or a function key; with Vim mode on it can also be a leader sequence, the leader and then one to three keys, such as Space x t. Sequences run through the leader like the built-in ones and show in the leader hints; with Vim mode off they do nothing, and Settings marks them “Inert with Vim off”. Built-in leader keys always win, so a sequence may not start on one: Space t is the template picker, so Space t x is refused. A key you give a command wins over every default, the editor’s own keys included (a command on Mod+Backspace runs even in the editor, where that key would delete to the line start), and the recorder says which default it takes over. Two of your own keys cannot share one: the recorder refuses a key another of your bindings holds, and marks both rows when config.toml has made them share. When the command cannot run where you are, the key does nothing and a short note says why, for example “Restore from Trash only works on a note in the Trash”. From the ex line, :bind <C-BS> note.trash or :bind <leader>xa note.archive binds and :unbind command note.trash takes the key away. In config.toml the keys live under [keymaps.commands], as "note.trash" = "Mod+Backspace" or "note.archive" = "Leader x a".
Use the note context menu, the command palette, or :move / :mv to move a note. The move prompt autocompletes folder paths, and the ex command accepts a destination directly like :mv archive/Reference.
With the sidebar focused, Mod+Backspace (⌘⌫ on macOS, Ctrl+Backspace on Windows and Linux) moves the note under the sidebar cursor to the Trash, after the same confirm Move Note to Trash shows; in Vim mode x does the same. When that note is part of a multi-selection, the whole selection goes, with one confirm (“Move 3 notes to Trash?”). Escape on the confirm leaves everything as it was, and after the move the cursor sits on the row that took the note’s place, still in the sidebar. A folder is not trashed this way, since deleting a folder takes everything inside and cannot be undone: delete it from its menu (m, or right-click). The palette’s Move Note to Trash and Move Note to Archive, and any key you gave them, follow the sidebar the same way: with the sidebar focused and its cursor on a note, they act on that note (or the selection it is in) rather than the note open in the editor. Rebind the chord as Move sidebar note to Trash (nav.sidebarTrash) under Settings → Keymap, or unbind it; x is Delete selected result (nav.delete).
An action in a list view (Archive, Trash, Quick Notes, Tags, Tasks, Unresolved Links, a folder’s Gallery, Workflows, the Timeline) can take a chord such as "nav.delete" = "Ctrl+Backspace" or "nav.delete" = "Mod+Backspace" in config.toml, or from Settings → Keymap, and so can the sidebar’s Delete selected result. Unlike the single letters, such a chord works with Vim mode on or off. Mod means ⌘ on macOS and Ctrl on Windows and Linux, so one config.toml serves both. A global shortcut keeps its key everywhere, though: an action bound to Mod+P would lose to Search notes, so Settings marks such a binding “Never fires” and names the shortcut that has the key.
You do not need to remember where a tab action lives. The command palette exposes direct entries for closing, splitting, pinning, referencing, floating-window, and reveal actions.
Type / at the start of a line or after whitespace to open an inline insert menu for common Markdown structures: headings, lists, to-do items, callouts, code blocks, dividers, tables, math blocks, links, images, and new-note links. The same slash menu is available in the Quick Capture window.
Turn a blockquote into a colored callout (an Obsidian-style admonition) by starting its first line with > [!type], optionally followed by a title, like > [!warning] Heads up. Typing [! inside a blockquote opens an insert menu of the callout types: filter by name (aliases match too, so warn finds Warning and tldr finds Abstract), move with the arrow keys or the Vim/Emacs completion chords (Ctrl+J / Ctrl+K, Ctrl+N / Ctrl+P), and press Enter, Tab, Ctrl+Y, or click to drop in the syntax. The type sets the color: note, info, abstract/summary/tldr render blue; tip/hint/important and success/check/done green; question/help/faq and example purple; warning/caution/attention yellow; danger/error, bug, and failure/fail red; and quote/cite a neutral gray. Types are case-insensitive, and an unrecognized one still renders as a neutral note, so callouts pasted in from Obsidian keep working. Put - or + right after the type to make a callout foldable, as in Obsidian: > [!example]- Screenshots starts collapsed and > [!example]+ Screenshots starts expanded. Click the title row in Preview, or the chevron after the title in Edit mode, to open or close it; the fold keys (zc and zo, or Ctrl+Alt+F and Ctrl+Alt+U, Cmd+Option+F and Cmd+Option+U on macOS) work on it from its title line or any line inside it, and Fold All (zM) includes it. A collapsed callout starts closed each time the note opens and prints open in a PDF export; folding never changes the note. To make one without typing the syntax, or to change or remove one, use the callout menu (next card).
Right-click text in the editor and choose “Turn into callout…”. A second menu opens in the same spot, “Callout type”, listing every type with its icon: Note, Info, Abstract, Tip, Success, Question, Example, Warning, Danger (Error), Bug, Failure and Quote. An Error callout is a Danger one, since error is its alias. Move with the arrow keys and press Enter, click, or type to filter: aliases count, so error, caution or tldr find their type. Selected lines become the callout whole, line by line. With nothing selected, the paragraph under the pointer does, a whole list when it is in one. A plain blockquote just gains the > [!type] line on top. A callout made from part of a paragraph, or right beside a quote, gets a blank line so it stands on its own. Right-click inside a callout, written out or drawn as a card in Live Preview, for “Change callout type…” and “Remove callout”. Change type checks the current type, and keeps the title and any + or - fold marker. Remove drops the title line, keeps a custom title as a plain first line, and takes one level of > off the text, so a quote or callout nested inside stays as it was. From the keyboard, run “Set Callout Type…” from the command palette, or press Space l a in Vim mode, to open the same menu at the cursor. “Remove Callout” is in the palette too, and either command can take a key of its own (Alt+Enter on its row). In Vim mode, m or Shift+F10 on a selection opens the whole right-click menu. Each change is one step for Undo. Code blocks and the note’s properties never become callouts: there the menu shows “Turn into callout…” greyed out with the reason, and the command says why. With Vim mode off, the menus answer to the arrow keys, Enter and Escape, and letters filter.
By default, checking a task (- [x]) just fills its checkbox. Settings → Editor → Completed task style can also strike the text through, gray it out, or both, so finished items visually recede in the editor and the reading view while the checkbox stays checked. There are matching command-palette entries (Completed Tasks: Strikethrough / Gray / Strikethrough + Gray / No Style). Nested sub-tasks keep their own state, so a completed parent never strikes an unchecked child, and formatting like bold or [[wikilinks]] inside a done task is styled along with the rest. It defaults to off, so existing notes look unchanged until you opt in.
Typing @ in normal text opens suggestions: the date shortcuts (Today, Yesterday, Tomorrow, Now), a Date… entry that opens a calendar for any other day, plus any notes matching what you type. Choosing a date inserts an ISO date like 2026-04-15; choosing a note inserts a [[wikilink]], so @ is a quick alternative to [[. A bare @ leads with just the dates: start typing letters and matching notes appear. In the calendar, arrows move a day or a week, PageUp/PageDown change the month (Shift for the year), typing a date jumps to it, and Enter inserts.
Select text in the editor and a Notion-style bubble toolbar pops up over it: bold, italic, strikethrough, highlight, inline code, math, a link, and a comment, plus a “Turn into” menu that re-types the block (Text, Heading 1–3, bulleted/numbered/to-do lists, quote, code). The footer shows the focused action’s keyboard shortcut. The same inline formats have shortcuts that work on every platform, in or out of Vim mode (Mod is ⌘ on macOS, Ctrl on Windows/Linux): Mod+B bold, Mod+I italic, Mod+E code, Mod+K link, Shift+Mod+S strikethrough, Shift+Mod+H highlight, Shift+Mod+M math. Press Mod+/ to focus the toolbar, then walk it with the arrow keys (or h/j/k/l in Vim mode); Enter applies, Esc returns to the text. Once a formatted word is typed, Ctrl+. (Windows/Linux: Alt+]) steps the cursor past the closing markers so you can keep writing outside them, and Ctrl+, (Windows/Linux: Alt+[) steps back over the previous ones. Repeat either to walk the line pair by pair, brackets included. Pressing the format shortcut a second time also leaves the span.
Text pasted from a terminal, an email, or a model reply often arrives hard-wrapped at 80 columns, and in the editor every one of those source lines spills a word or two onto a second row. The preview already reflows such prose; press Alt+Q (macOS: Ctrl+Q) in the editor to join the lines of the paragraph under the cursor into one line, so the editor wraps it to the pane too. With a selection it reflows every paragraph the selection touches. Headings, list and quote markers, tables, code blocks, $$ math, and explicit line breaks (two trailing spaces, a backslash, <br>) are left alone, and the change is a normal edit, one undo away. It works with Vim mode on or off, is remappable as editor.reflowParagraph under [keymaps] in config.toml, and is in the command palette as “Reflow Paragraph”. In Vim mode it is also the gq operator: gqip reflows the paragraph, gqj two lines, Vgq a selection, and gw does the same while keeping the cursor in place.
Built-in templates cover engineering (ADR, RFC, Bug Report, Postmortem, Meeting Notes, 1:1) and personal use (Daily Note, Weekly Review, Reading Notes, Journal, Project Kickoff, To-do), and you can author your own under Settings → Templates. A template is plain Markdown with optional frontmatter and variables like {{title}}, {{date}}, {{week}}, and {{cursor}}, substituted at creation. Custom templates are saved as .md files in .zennotes/templates/, so they stay as portable as everything else; a template folder makes the notes in it templates too. Since 2.46 they also work in the self-hosted web client and on a remote vault served by ZenNotes server 2.46 or later, and a template saved in one client shows up in the others. Three variables stay live instead of being substituted: {{modified_date}}, {{modified_time}} and {{modified_datetime}} are left in the note and render as the time the file was last saved, in the editor and the reading view alike.
Pin a companion note or PDF in the reference pane, then toggle the connections panel to inspect backlinks and unresolved links while you draft. Under a note's missing links, the All unresolved links in the vault row opens the Unresolved Links view, the same list for the whole vault.
Use the configured Zen shortcut to strip away the title bar, sidebar, note list, tabs, pane headers, side panels, and status bar. Only the active editor, preview, or split view stays visible.
Use [[wikilinks]] or standard Markdown links. Both are first-class. A [text](Note.md) link navigates just like a [[wikilink]] everywhere: the preview, the editor’s live preview, and the follow-link motion. Internal links (relative paths and #heading anchors) open the note; external links open in the browser, including bare domains you typed without a scheme, like [site](google.com). In Edit and Split a plain click follows a rendered link (click one the cursor is inside to edit it instead), Cmd/Ctrl-click always follows, and Markdown links show a pointer cursor on hover. In normal mode the follow-link motion (gd) opens the link under the cursor and pins PDFs into the reference pane. If the target note does not exist yet, following the link any way (click, Cmd/Ctrl-click, or gd) offers to create it after you confirm, instead of leaving a dead link; hold Cmd (macOS) or Ctrl (Windows/Linux) while clicking the link, or use gD in normal mode, to create it at once at the suggested path: Inbox, named after the link text. A link named like one of your daily, weekly or monthly notes, such as `[[2026-11-03]]` while daily notes are on, creates that note instead, in its folder and from its template, the way the calendar does, so it shows up on that day; a link that names a folder (`[[journal/2026-11-03]]`) still makes a plain note there. A link at a note that does not exist yet is drawn muted with a dashed underline, in the editor and in the reading view, so live links stand apart from ones that would create a note; the Unresolved Links view (Space u) lists all of them in the vault. Rest the pointer on a wikilink, or press K on it in Vim mode, to edit or create its note in the link popover without leaving the note you are in. Prefix a wikilink with `!` to embed rather than link: `![[Note]]` inlines the target note content in the reading view and PDF export (recursively, with cycle protection), so a master note can pull in sub-notes and export to PDF as one document. `![[image.png]]` embeds an image and `![[drawing.excalidraw|600x400]]` embeds a drawing; both take optional `|width` or `|WxH` size hints (`![[image.png|300]]`), and the markdown form carries the same hint after the alt text (``). Right-click a web link or an email address, in the editor or the reading view, to open it or copy it (the address itself, without mailto:); gy in normal mode, or Copy Link Under Cursor in the palette, copies the one under the caret.
Link a note before it exists, like [[Garden Plan]], and the Unresolved Links view keeps it for you: every [[wikilink]] in the vault that points at a note that does not exist yet, grouped by the missing note with the most-linked first, and under each one the notes that link to it and the line each link sits on. Open it with Space u in Vim mode, :unresolved, Open Unresolved Links in the command palette, or the All unresolved links row under a note's missing links in the Connections panel. Enter on a name creates the note where gD would (in Inbox, named after the link) and opens it, and the name leaves the list; Enter on a line opens the linking note with the cursor on the link; K (Shift+Cmd+K, or Shift+Ctrl+K on Windows and Linux) writes the missing note in the link popover without leaving the list. In Vim mode j / k move, gg / G jump to the ends and / filters; with Vim mode off the arrows, Enter and Escape do the work. A link is listed exactly when the editor draws it as unresolved: a heading ([[Note#Heading]]), block ([[Note^id]]) or display-text ([[Note|text]]) link to an existing note resolves, so does a link to a file in the vault or to a .base database, and a [[link]] inside a code block or inline code is text, not a link.
Rest the pointer on a [[wikilink]] in the editor and the link popover opens: the note the link names, in a small floating editor over the note you are in. It is the note itself, not a preview: what you type there is saved to it like any other edit, and shows up in any tab that has it open. Move the pointer away and it closes; click or type in it and it stays until you press Escape or click outside it. A link to a note that does not exist yet offers Create note instead: press Enter (or click it) and the note is created where gD would put it, then opens in the popover, ready for its first line. From the keyboard, put the cursor on a link and press K in Vim mode, or Shift+Cmd+K (Shift+Ctrl+K on Windows and Linux) with Vim mode on or off. The popover takes the keyboard: K on a link inside it moves on to that note, Cmd+Enter (Ctrl+Enter) opens the note in a tab, and Escape closes it and puts you back on the link you came from, cursor where it was. In Vim mode the first Escape leaves insert mode as usual and the next one closes the popover. A [[Note#Heading]] link opens it on that heading. To keep the popover to the keyboard only, turn off Settings → Writing → Link popover on hover.
On desktop, enable application prefixes such as zotero, obsidian, or vscode under Settings → Editor → Links → External application links. Separate prefixes with commas; they are saved in config.toml. Use ordinary Markdown, for example [Paper](zotero://open-pdf/library/items/W78FUE98). Editor clicks, Cmd/Ctrl-click, preview links, and Vim gd open enabled links in the installed application. A disabled application link offers Open settings, never note creation. If the application cannot open the link, ZenNotes shows an error.
End a Markdown body line outside frontmatter and fenced code with a ^block-id marker. IDs start with an ASCII letter or digit and may then contain ASCII letters, digits, and hyphens (e.g. - Ship the picker ^ship-it). Link to it with [[Note^ship-it]]; following the link opens the note scrolled to that exact block, the way [[Note#Heading]] reaches a section. Put the marker on its own line to tag the block above it (a paragraph or a fenced code block) without touching its text. Typing ^ inside a wikilink lists the target note's ids with the block text beside each one, and [[^id]] points at a block in the note you are already in. Embedding follows the same rule: ![[Note^ship-it]] inlines just that block rather than the whole note, bringing a bullet's children along with it. Obsidian's spellings work as-is, so a shared vault keeps its block links: [[Note#^id]], [[#^id]], and markdown-style [text](Note.md#^id) all reach the block. A marker appended to content is addressing, not prose, so it stays hidden in the reading view and in the editor until your cursor is on the line. The Connections panel says which block a note reached for instead of only that it linked here.
New Drawing (from the command palette, the home view, or a folder's context menu) creates a .excalidraw file that opens in a full Excalidraw canvas: shapes, arrows, freehand, text, image import. Drawings live in your vault like any other file, embed into notes with ![[drawing.excalidraw]] (optionally sized, like |600x400), and .excalidraw.md files from Obsidian open too.
Settings → Editor → Math renderer switches math from KaTeX to Typst. With Typst active, shared definitions can live in preamble notes under a typst/ folder named after tag paths: a note tagged physics/quantum layers typst/physics.md then typst/physics/quantum.md into its math scope, alphabetically within a level, so notation stays consistent across a topic without repeating definitions per note. Preamble notes never contribute #tags: a preamble is Typst source, where #let vec(x) = bold(x) defines a variable that formulas call as #vec, so the app, the CLI, MCP, and the self-hosted server all leave them out of the tag index. Settings → Editor → Typst preamble folder renames the folder if you already keep ordinary tagged notes in one called typst, and the name is stored in the vault so it travels with it.
Rename a note and every [[wikilink]] pointing at it across the vault rewrites itself to the new name. No dead links. It handles every form ([[Note]], [[Note|alias]] keeping your display text, [[Note#heading]], [[Note^block]], embeds ![[Note]], and path-style [[folder/Note]]), skips anything inside fenced or inline code, and only touches links that actually resolved to that note, so notes that share a title never get cross-wired. It runs in the vault layer, so it applies however you rename (the editor, the MCP tools, the CLI, or the HTTP API), on desktop and the self-hosted server alike. Renaming or moving an asset does the same for its embeds and file links.
Drop or paste files into a note to insert local assets. ZenNotes copies them into the vault's assets/ folder (the same for drag-drop and paste, whether you keep notes in inbox/ or at the vault root; a pasted screenshot is named for the moment you pasted it, such as Pasted Image 2026-10-19 142312.png, while a copied file keeps its own name), can reveal them from the app, and treats PDFs specially in preview and reference workflows. In the sidebar you can drag an image, PDF, or any attachment onto a folder to move it, just like a note, or use its Move… context-menu entry. Renaming or moving an asset (from the sidebar, the Assets view, a rendered image's menu, or by dragging it onto a folder) rewrites every note that referenced it, ![[assets/old.png]] embeds and  links alike, in the style each link was written, the same way renaming a note updates its wikilinks.
A .csv file in your vault is a full Notion-style database, with zero new dependencies. The same data shows up as an editable Table and a Board grouped by a select field, fields are typed (text, number, checkbox, date, select, multi-select, note link) with sort, filter, and a raw-CSV toggle, and every row keeps a stable id so external edits round-trip cleanly. Each saved view keeps its own columns and rows, so one wide CSV can carry several narrow views. A table view’s Columns button, beside Filter, reads “Columns 5 of 44” once some are hidden and opens a checklist of the view’s columns with a find field, Show all and Hide all (press c in the grid in Vim mode); a column’s ⋯ menu has Hide column too, and the last visible column always stays. The + beside the view tabs offers New table view (which opens Columns straight away), New board view and Duplicate this view, which copies its filters, sorts, columns and picked rows; a view tab’s right-click menu has Duplicate view as well. To show only certain rows, select them (the row checkboxes, Space in the grid, or x in Vim mode) and choose Show only these in this view: the view then keeps those picked rows, applies its filters and sorts to them, and says “Showing N picked rows” under the header, with Edit picks and Show all rows. A row you add in that view joins its picks, a deleted row simply drops out, and a Board view shows its picked rows the same way. The command palette has Choose Database Columns, New Table View, Duplicate View, Show Only Selected Rows and Show All Rows, and each can take a key of its own. Open any row as a real Markdown record page whose frontmatter mirrors its properties (its Open button, Open page in its menu, or o in Vim mode). A record can be linked once it has a page; to give every record one at once (a database converted from a CSV starts with none), choose Create pages for all records in the database’s ⋯ menu or the command palette, or press O in the grid in Vim mode. You can also link to a database itself: type [[ in any note and pick it (databases appear alongside notes and assets) to drop a [[Database]] link that opens the grid on click. A database also opens from its sidebar row like a note: click it, or press Enter or l on it in Vim mode (the row’s m menu carries Open database too); the chevron still expands the folder to browse its record pages, and the open grid closes like any tab. The table is the source of truth: editing a cell or adding, renaming, or removing a field updates an open record page’s metadata immediately, leaving the body intact, and the in-editor frontmatter renders as a compact properties card. Create one with New Database in the command palette or by right-clicking a folder → New database.
Right-click a folder in the sidebar and choose New Kanban for a board of its own: one per class, project or client, each with its own cards. It is a database (Untitled Kanban.base) with a Name and a Status of To do, Doing and Done, and it opens on its Board, so it works on the phones, a self-hosted server, the web app and zn base like any database. New Kanban is also in the command palette, Space k in Vim mode and :kanban on the ex line, which create it in the folder under the sidebar cursor while the sidebar has focus and where new databases go otherwise (Settings → Vault → Default Locations); :kanban Biology names the folder. Double-click the title to rename it. Add card at the foot of a column adds a card there: type its title and press Enter, and the field stays open for the next one. Drag a card to another column, or move it from the keyboard (see the Database board shortcuts). Add column makes another status, and a card with no status sits in a No status column that shows only while it holds a card. Open a card as a page for its notes, or switch to the Table to add fields such as a due date. This is separate from the Tasks Kanban board, which shows the - [ ] tasks of the whole vault.
A note often starts with a small pipe table that outgrows inline editing. Put the cursor in it and run Convert Table to Database… from the command palette (:table_to_database on the ex line, or Space l d in Vim mode); in a rendered table, the same entry sits at the bottom of the cell menu (right-click, or m in Vim mode). Confirm a name, prefilled from the heading above the table or the note’s title, and ZenNotes creates a <Name>.base database where new databases go (Settings → Vault → Default Locations), then replaces the table in the note with a [[Name]] link that opens the grid. Every column becomes a field, typed the way an opened CSV is (checkbox, number, date, text) so the Board and filters work at once; cell text travels verbatim, inline Markdown included, and the CSV layer takes care of commas and quotes. Column widths you dragged in the editor carry over; alignment does not, since a grid has none. The swap is an ordinary edit: Undo brings the table back while the database stays in the vault, and the confirmation toast offers an Open button if you want to jump straight to the grid.
Database cells can link the notes you already have instead of hard-coding every value. Typing [[ in a text cell opens the same note search as the editor and inserts a wikilink. A Note link column (types “Note link” / “Note links” in the field menu) stores wikilinks properly: pick notes from a searchable list, and the saved chips show each note’s title and open it on click. And a Select or Multi-select column can auto-discover its options from your vault: open the column’s ⋯ menu and choose Options: all notes, notes in folder…, or notes with tag…; the cell popover then suggests matching notes live, and anything you pick is saved as an ordinary option so boards and filters keep working. Every picker is keyboard-driven: type to search, ↑/↓ or Ctrl+N/P to move, Enter to pick, Escape to close.
Inline $…$ and display $$…$$ math render via KaTeX by default; Settings → Editor → Math renderer switches the typesetter to Typst. Five fenced block languages turn into live diagrams: mermaid for flow, sequence, and every other Mermaid diagram type, drawn by Pele in your theme; d2 for architecture and system diagrams with D2 (d2lang.com), nested containers, sql_table data models and sequence diagrams included, coloured from your theme unless the diagram picks a D2 theme of its own; tikz for LaTeX-native coordinate systems (runs on-device); jsxgraph for interactive geometry; and function-plot for Cartesian plotting. A mermaid or d2 fence also draws inline in the editor with live preview on: the diagram stands in for the source until your cursor enters it, and arrow keys or Vim j/k step into it like rendered math. Mermaid labels take <br> breaks, Markdown bold or italic, the HTML tags <b>, <i>, <u>, <sub>, <sup>, <code> and <kbd>, and $$…$$ math, typeset with KaTeX even when Typst is your math renderer; any other tag is dropped with its text kept. D2 labels may be Markdown, but icons, images and links are not drawn, so a diagram never reaches the network; the D2 compiler is a large download that loads the first time a note holds a d2 fence. Each block is ordinary Markdown on disk.
In Edit mode every fenced code block carries its language at the top right, as a button reading typescript ▾ (or text ▾ when the fence names none), with a copy button beside it. Press the language to open the “Code block language” picker: a find field, then every language the editor can highlight, by name, the current one checked. Type to narrow the list: a language’s tags count, so golang, yml or sh find Go, YAML and Shell, and an exact name comes first, so c then Enter is C. A pick rewrites only the opening fence’s language word, so ``` becomes ```typescript, keeping the fence’s backticks or tildes, their count and anything after the word, such as a title; the cursor stays where it was, and one Undo takes it back. “Text (plain)” takes the language away. Languages you installed under Settings → Editor → Languages are listed too. A block that names no language is guessed at, when it is long enough to tell: it is highlighted with the guess and its button reads python · detected, muted, in a dashed outline. The guess is never written to the note; the picker’s first row, “Python (detected)”, writes it. Tiny or ambiguous blocks stay text, and the reading view colours exactly the blocks the editor guesses, in the same language. From the keyboard, run “Set Code Block Language…” from the command palette, or press Space l l in Vim mode, with the cursor in a block; it can take a key of its own (Alt+Enter on its row). In the picker the arrows, Ctrl+N / Ctrl+P, Enter and Escape work with Vim mode on or off; with Vim mode off the find field has the keyboard and every letter is text, and with it on the list does, where j / k move and / goes to the find field. Turn the guessing off with Settings → Editor → Detect code block languages.
With the KaTeX renderer, each unstarred \begin{equation}…\end{equation} inside a display math block receives the next number in document order. Numbering stays consistent between the live editor and Preview.
Settings → Editor → Writing can show H1 through H6 labels before Markdown headings. Every heading also has a disclosure arrow that folds its section, and so does every list item with indented lines under it (a bullet, a numbered item or a task): the arrow beside its marker folds those lines, in Edit and in Preview, and the item line stays in view. Click the arrow, use Ctrl+Alt+F and Ctrl+Alt+U (Cmd+Option+F and Cmd+Option+U on macOS), or use zc and zo in Vim mode; on one of the lines under a list item, they fold the item itself. Fold All (zM) folds every heading and every list item, nested, so opening a heading shows its tasks one line each. Code blocks, tables and quotes keep their existing folds too. Folding only hides lines: the note, and the Tasks view, are unchanged.
Settings → Editor → Text replacements expands short triggers as you type. The default rule turns -> into →, and you can add symbols, words, or longer phrases. The longest matching trigger wins.
Set the editor tab size from 1 through 8 spaces under Settings → Editor → Writing. Tab and Shift+Tab indent and outdent lines (`>>` and `<<` in Vim mode). Headings stay at the margin: Markdown reads a heading indented four spaces as a code block, so indenting leaves heading lines where they are and indents the rest. Press Ctrl+Tab to switch to the most recently used note, then press it again to alternate between the same two notes.
The sidebar footer gives you direct access to Files, Help, and Settings, so utility screens stay discoverable. A narrow sidebar degrades the row in steps instead of clipping: first the file count folds into the Files tooltip, then the labels drop and the three actions stand as icons.
Moving a note to Trash asks for confirmation before anything is deleted. The Trash view separates restore from permanent delete, and a trashed note opened in the editor offers the same two actions in its header, Restore and Delete permanently, in place of Archive and Move to Trash. In a question, Enter presses the highlighted button, and one that deletes for good or discards something opens on Cancel, so Enter alone keeps everything; Tab to the button that goes ahead, then Enter.
ZenNotes organizes your vault into a handful of system areas you move notes through over their lifetime, plus folders you create freely. This section covers every view in the sidebar, how to sort, filter, and group what you see, and every operation you can perform on a note or folder.
Your vault is a normal directory of Markdown files on disk. On top of it, ZenNotes defines four built-in lifecycle areas: Inbox, Quick Notes, Archive, and Trash. These areas exist conceptually even if you rename their sidebar labels. Tags and Files give you two more ways to slice the same notes and assets without moving anything.
Most actions described here are reachable several ways: a default shortcut, a command-palette title (open it with Shift+Mod+P), an ex command (type ':' in Vim normal mode), a right-click or 'm'-key context menu, and the zn CLI. Pick whichever fits your flow.
Six destinations in the sidebar. The first four are lifecycle stages a note passes through; the last two are lenses over your whole vault.
Your primary workspace for active notes. View all notes in the inbox folder (or at the vault root, depending on settings), with configurable sort, filters, and folder grouping. Open it from the sidebar 'Inbox' entry or the command palette 'Go to Inbox'.
Lifecycle
A capture buffer for fast, low-friction notes, sorted newest-first. Reach it from the sidebar, command palette 'Go to Quick Notes', or create-and-jump with the quick-capture shortcuts. The Quick Notes folder is system-wide and cannot be moved.
Lifecycle
Long-term storage for inactive notes you want to keep without cluttering Inbox. Open via the sidebar 'Archive' entry or command palette 'Go to Archive'. Notes here stay fully searchable; Unarchive returns them to Inbox.
Lifecycle
A recovery bin for deleted notes. Open with the :trash ex command, command palette 'Go to Trash', or the sidebar 'Trash' link. Notes wait here until you Restore them or delete permanently.
Lifecycle
Browse and filter notes by hashtag across the whole vault, with a multi-select chip strip. Open with :tag (optionally :tag foo bar to preselect), command palette 'Open Tags', or the sidebar Tags section.
Lens
Browse every non-note file (images, PDFs, audio, video, binaries) in the vault tree. Open with command palette 'Go to Files' or the Files link in the sidebar footer. Open files in tabs or the reference pane.
Lens
Where your main notes live is governed by Settings → Vault → Primary notes location. In Inbox mode (the default), regular notes live in an inbox/ folder and other folders sit under archive/. In Vault root mode (Obsidian-style), notes live at the vault root with no dedicated inbox/ folder. This choice changes how the sidebar is laid out, where new notes are created, and which 'New Note' commands appear (for example, 'New Note in Inbox' versus 'New Note in Vault Root'). The setting persists across sessions.
Inside the Inbox view you can multi-select notes and folders for bulk operations, drag notes into folders or onto other panes, and assign emoji icons to folders. The note list updates automatically as you change the sidebar selection, showing notes and assets for the current folder.
Quick Notes are ordinary Markdown files that live in the quick area, listed in reverse-chronological order so the newest capture is always on top. Create one with Shift+Mod+N, Space q in Vim mode, the '+' button or 'n' key inside the Quick Notes view, or command palette 'New Quick Note'. ZenNotes focuses the title field immediately so you can start typing.
On desktop you can also pop a small floating capture window with Shift+Mod+Space (a system-wide hotkey that works even when ZenNotes is hidden), Space q via the leader, or command palette 'Quick capture'. It remembers its position and size, and notes you jot land in the Quick Notes folder.
Titling is configurable in Settings → Editor. Toggle 'Date-titled Quick Notes' to name notes by ISO date (for example 2026-05-29) instead of a timestamp, and set a 'Quick Note prefix' (default 'Quick Note') that is prepended to the title. Leave the prefix blank for a bare date or timestamp.
Move a note from Inbox to Archive without deleting it. Use the command palette 'Archive', the context menu, or 'd' in some list views. Content is preserved and the note stays searchable.
Archive
Send an archived note back to Inbox with the 'u' key in the Archive view, the context menu 'Unarchive', or command palette 'Restore'/'Unarchive Note'. The sidebar updates the note's folder status immediately.
Archive
Filter, sort, and search archived notes. Quick-action buttons cover Open, Unarchive, and Move to Trash. Keyboard: j/k navigate, Enter or o open, u unarchive, d delete. The full context menu (right-click or m) adds open in new tab, rename, move, duplicate, copy as wikilink, copy path, reveal in file manager, and open in floating window.
Archive
Soft-delete a note with command palette 'Move Note to Trash', the 'd' key in list views, or the context menu. In the sidebar, x (Vim mode) or Mod+Backspace (either mode) trashes the note under the cursor, or the selection it is in with one confirm, and the palette's Move Note to Trash acts on that row while the sidebar has focus. A confirmation dialog shows the note title. The note moves to the trash area and is recoverable.
Trash
Recover a trashed note back to Inbox with the 'r' key in the Trash view, the context menu 'Restore', or command palette 'Restore Note from Trash'. It returns to its original folder path if that path still exists.
Trash
Permanently remove a single note with the 'd' or 'x' key in the Trash view (confirmation: 'This cannot be undone'). Empty Trash deletes every trashed note at once after a single confirmation showing the count. Both are irreversible and available only in the Trash view.
Trash
The Tags view shows every hashtag in the vault as a chip strip with per-tag counts. Click chips to select or deselect them; notes carrying every selected tag appear below; a Match: Any toggle switches to union. A search box filters within the results. Selections accumulate as you click; press c or the Clear all chip to reset them, and right-click a chip for Unselect others. Tags can be hierarchical with slashes (for example #project/active), and they work in any script: non-Latin tags like #тест (Cyrillic) or #标签 (CJK) are recognized, render as clickable pills in the editor and preview, and appear here. Headings (# x) and hex colors (#1971c2) are still not treated as tags.
Under each note the view lists its tagged blocks: every list item, paragraph, quote, or table row that carries a selected tag, so several unrelated ideas kept in one note show up one by one. A tagged list item brings its nested items along, and a tag on a heading tags its whole section, shown as the heading with the first lines under it. Tags in frontmatter tag the whole note, so a note tagged only there stays a plain row, and a #tag inside code is never a tag. The header counts notes and blocks, and the filter narrows to the blocks whose text matches (a note whose title matches keeps all of its blocks).
Open the view with command palette 'Open Tags', or the sidebar Tags section. The :tag ex command opens it, and :tag foo bar replaces the current selection with those tags in one step. Inside the view, j/k move through notes and their blocks, } and { hop from note to note (Vim mode), Enter or o opens a note or jumps to a block's line with the line highlighted, '/' focuses the filter, and ':' opens a view-local ex prompt. The view live-extracts tags from the active editor buffer as you type, and a tagged block you just wrote in an open note lists right away.
ZenNotes treats your vault as a file-based, Obsidian-compatible store: loose files anywhere in the vault count as assets. Images, SVGs, PDFs, audio, video, and generic files can open in tabs or the reference pane. New referenced files default to the vault root rather than a forced attachments folder, though legacy locations such as attachements/ and _assets/ are still recognized.
Embed an asset with  or the Obsidian-style ![[image.png]], or paste/drop an image into the editor to auto-insert it (a pasted screenshot is named for the moment you pasted it, such as Pasted Image 2026-10-19 142312.png). Wikilink autocomplete ([[) also completes asset paths. Reach the asset views from the Files link in the sidebar footer (command palette 'Go to Files') or the Assets tab that appears when a folder or asset is selected.
Assets render in two layouts you switch from the note-list header: a grid of thumbnail cards (grid icon) and a compact list with names, paths, and sizes (list icon). Your layout choice persists for the session. From the asset views you can sort, filter, search, drag assets into notes, delete unused assets, and on desktop right-click to reveal an asset in the file manager.
The sidebar's Assets row answers the m shortcut like every other row: a context menu with Open Assets, plus sort by name, type, size, last modified, or times used. Picking the active field again flips its direction, and the choice persists like the Assets view's own sort.
Several entry points depending on where you want the note to land.
Every operation works from the command palette and most from the right-click / 'm'-key context menu. Multi-select in the sidebar applies compatible operations to the whole group.
Two related folder-path commands round this out: 'Copy Current Folder Path' (vault-relative, like inbox/Work) and 'Copy Current Folder Absolute Path' / '…Server Path' for the full path. On desktop, 'Reveal Note in File Manager' (context menu 'Reveal in Finder') jumps to the note's location in Finder or File Explorer.
Sort the note list from the sort icon (gear) in the note-list header, from Settings, or from the command palette. Options are Name (A→Z and Z→A), Updated date (newest or oldest first, the default is newest first), Created date (newest or oldest first), and Manual. Choose Manual to disable automatic sorting and drag notes up and down to set a custom order; the order persists per folder. Your sort choice persists per view.
Toggle 'Group by kind' (command palette 'Group Notes by Kind' / 'Ungroup Notes by Kind') to list folders and assets in their own sections separate from notes, instead of mixing them in a flat list.
Filter the current list by pressing '/' to focus the filter box (or use the filter input in the folder view). Matching is a case-insensitive substring across title, path, and the first-line excerpt, with instant results as you type. An icon indicates when a filter is active; press Esc to clear it. Filtering is available in every list view, including Inbox, Archive, Quick Notes, Tags, and Tasks. The Tasks, Tags, and Trash views also accept '/' to focus their local filter.
Create as many folders as you like under your primary notes area and Archive. Folder commands live in the sidebar context menu and Settings → Folders.
Right-click a folder in the sidebar, or use Settings → Folders. Prompts for a name; nested paths like Inbox/Work/Projects create the full hierarchy at once.
Create
Sidebar context menu 'Rename…' or Settings → Folders. Updates every contained note's path, preserves subfolder structure and folder-icon assignments, and rejects invalid characters.
Rename
Sidebar context menu 'Delete…' or Settings → Folders. The dialog lets you cancel, move contents to the parent, or delete the folder and everything in it. Moving preserves access; deletion is permanent.
Delete
Right-click a folder and choose 'Set icon' to open the emoji picker. The icon shows in the sidebar next to the folder name and is saved in vault settings. Clear it to reset to the default.
Icons
Click the chevron beside a folder, or use Left/Right arrows when the sidebar is focused. Right-click a section header or use the command palette to 'Collapse all folders' or 'Expand all folders'. Collapsed state persists per folder.
Collapse
Toggle 'Auto-Reveal Active Note' (command palette or sidebar settings) so opening a note expands its ancestor folders and scrolls it into view in the sidebar.
Auto-reveal
The Gallery shows one folder's notes as a grid of cards. Each card leads with the note's cover (an image in the vault, an Unsplash photo or a gradient, cropped to fill the card at the cover's focal point, banner_y), then its title and date. A note without a cover gets a quiet card with the first letter of its title. Each folder opens as a tab of its own, named after the folder.
The header shows the note count, a Sort menu (Updated, the default, puts the last edited first; Created puts the newest first; Title goes A to Z) and an Include subfolders switch, off by default, that adds the notes in the folder's subfolders. Both choices apply to every Gallery and travel in config.toml as gallery_sort and gallery_include_subfolders under [view]. A database's record pages and drawings are left out.
Only the cards on screen are drawn, and a note is read for its cover only when its card scrolls into view, so a folder of thousands of notes opens at once. The Gallery works the same in a vault on a self-hosted server and in the web app, and at phone width it keeps two columns.
The single-letter keys are Vim-mode only; with Vim mode off the arrows, Enter and Escape do the work, and typing into the filter field always works.
Bring existing Markdown into the vault by dragging .md or .markdown files onto the window. On desktop the file opens in place (in an external file window) or is imported as a copy; on web its contents are read and a new note is created. The filename becomes the title, and frontmatter and content are preserved. Programmatic import is available through window.zen.importNote().
Attachments and assets follow the file-based model described above: drop or paste images and PDFs to embed them, link documents for download or open, and manage everything from the Files/Assets views. PDFs embed with a viewer (zoom and page navigation) and can be pinned into the reference pane. New referenced files default to the vault root.
Every lifecycle operation has a zn CLI equivalent for scripting and automation: zn list (filter with --folder or --tag), zn create / zn capture, zn rename, zn move (--folder inbox|quick|archive|trash, optional --subpath), zn duplicate, zn archive / zn unarchive, zn trash / zn restore, and zn delete --yes for permanent removal. Folders use zn folder list|create|rename|delete, and tags use zn tag list and zn tag find. Add --json to most commands for machine-readable output. Install the CLI from Settings → CLI.
The whole vault drawn as a map of notes and links, in 2D or 3D. Every note is a point, every link a line, regions come from your top-level folders, and the layout is frozen so the map stays a place you know.
Atlas is ZenNotes' answer to the graph view, built the way ZenNotes does things. Every note is a point sized by how linked it is, every [[wikilink]] (and markdown-style note link) is a line between two points, and regions come from your top-level folders, so the map reads as the vault's actual geography rather than an abstract hairball. Press v to switch between the flat 2D map and a 3D sky you can fly through: both use the same layout, so nothing shuffles when you lift off.
The layout is computed once and frozen: positions are cached, new notes land beside what they link to, and nothing else ever moves, so the corner where your project lives today is the corner where it lives next month. Atlas never writes into the vault, and Obsidian vaults render without any migration.
Open it with Space g in Vim mode, the Atlas row in the sidebar, or the Open Atlas command in the palette; Ctrl+W walks in and out like any pane. It is on by default, with a switch under Settings → Atlas that also hides the sidebar row, the command, and the Space g binding when off.
Press 1 through 4 to recolor the map so it answers a question. The layout never changes, only the paint.
The default view: regions colored by top-level folder, notes sized by how linked they are. The vault as geography.
1
Recent editing glows. See at a glance where you have been working this week, and which corners have gone cold.
2
Notes with no links stand out. The lens for finding what you captured and never connected to anything.
3
Notes holding regions together: the ones whose links cross folder boundaries and keep the vault one map instead of several.
4
Single-letter keys are Vim-mode only; arrows, Enter, and Esc always work, and every action is also on the toolbar chips along the bottom.
Any .csv file in your vault is a full database, à la Notion or Obsidian Bases, with zero new dependencies. The same rows show up as an editable Table and a grouped Board, fields are typed, and any record can open as a real Markdown page.
A database is just a CSV on disk plus a small sidecar file. ZenNotes stores the data as <Name>.csv (with an id column that gives every row a stable identity) and keeps field types, select options, and your saved views in a <Name>.csv.base.json file next to it. Because the data stays a plain CSV, external edits (a script, a spreadsheet, git) round-trip cleanly.
Create a database with 'New Database' from the command palette, or right-click any folder in the sidebar and choose 'New database'. Opening an existing .csv from the vault works too. Switch the raw-CSV toggle at any time to see and edit the underlying file.
A spreadsheet-style grid with inline cell editing. Add, rename, retype, and delete fields; sort and filter; and drive the whole thing from the keyboard.
Table
A Kanban-style board grouped by a select field. Add and switch views freely: every view reads the same rows.
Board
Open any row as a real Markdown note in a per-database folder. The table is the source of truth: its properties mirror into the note's frontmatter, the body is a freeform page, and a page icon shows which records already have content. Editing a cell (or adding, renaming, or removing a field in the table) updates an open record page's metadata immediately, leaving the body untouched, and the in-editor frontmatter renders as a compact properties card. A record can be linked once it has a page; Create pages for all records (the database’s ⋯ menu, the command palette, or O in the grid in Vim mode) gives every record one at once.
Pages
Each saved view keeps its own columns and rows, so one wide CSV can carry several narrow views.
Keys for a CSV database table while its grid has focus; the grid takes them before any global motion. The single-letter keys (h / j / k / l, H / L, 0 / ^ / $, g g / G, i, x, o, O, c, m, a, d d) and Ctrl+O / Ctrl+W belong to Vim mode, like every list in the app. With Vim mode off the arrows, Enter, Space, Esc, Delete / Backspace and Shift+F10 (or the Context Menu key) stay live, and the rest is in the row and column menus, the header buttons and the command palette.
Repeatable pipelines over your notes: find, filter, and rewrite in bulk, drawn as a graph you can read and run with one key. Off by default, and nothing writes without showing you the plan first.
A workflow is a plain Markdown file under .zennotes/workflows/ in your vault: a few frontmatter lines (name, description, trigger, status) and one pipeline step per line. Naming a wire is the whole grammar: `books = tag #book` opens a set, `good = books | where rating >= 4 | sort finished desc` refines it, and reading the same wire from two lines is a branch, no extra syntax. Because it is a file, it diffs cleanly, syncs with your vault, and travels by copy-paste.
The canvas and the text are the same artifact: the graph renders the file, edits round-trip losslessly, and layout is computed rather than stored, so no coordinates land in your vault (dragging a node saves one frontmatter key, and deleting that key snaps back to auto-layout). The editor completes from your actual vault: verbs, your tags, your fields, folders and note paths. Every wire on the canvas shows the live count of notes flowing through it.
Workflows are off by default because they can bulk-edit notes: enable them once under Settings → Workflows and the view, its sidebar row, its palette commands and its Space a binding appear together. New workflows start as drafts, saved but inert, until you activate them; activating one that writes lists exactly what it changes first. Eight working recipes ship in the New workflow gallery, each an ordinary file that copies into your vault and opens in the same editor as anything you write. A guided tutorial (Settings → Workflows → Start tutorial) teaches the whole loop on a practice folder it seeds and then removes, leaving your vault exactly as it started.
Running a workflow plans first: the engine structurally cannot touch disk, it returns proposed changes. The dry-run confirmation shows every change grouped and counted, with the affected paths, before anything is applied.
Plan
Applying journals every file’s pre-run bytes. Undo restores each one exactly, and a run that fails midway rolls itself back, including the steps that had already landed. Half-applied is not a state a run may leave you in.
Undo
all, tag and search never see the Trash or the Archive; those are reachable only by naming them (folder trash, folder archive). A bulk retag cannot touch files that vanish on the next empty-trash.
Scope
A workflow can only do what the app can do, which is why one you did not write is safe to read and run. Importing is a review, never an install: it must parse, what it writes is spelled out up front, any trigger it asked for is stripped back to manual, and it lands as a draft. Sinks that cannot be undone (a notification, the clipboard) are declared in the confirmation.
Safety
Run from the view with R, or from anywhere: every active workflow is a command-palette entry (Run: Reading log), and Run Workflow… opens a picker with descriptions and a writes tag on the ones that change notes. Both paths walk the same ladder: a fresh plan from what is on disk, an unsaved-edits question if the run would write a note you are mid-edit in, the dry-run confirmation, then apply. The receipt arrives as a toast carrying the Undo button, and when you ran from the view it also stays in the view’s footer, so the offer outlasts the toast. Drafts get no palette entry: a row whose only possible answer is an error is worse than no row.
Workflows run when you run them, and since 2.55 an active workflow whose trigger names an event (on note-created, on note-saved, on note-moved, on tag-added) also runs by itself for the note you change in the app, about a second and a half after it settles, with no confirmation and a receipt toast that carries Undo; schedule triggers parse but do not fire yet. Manual runs work everywhere your vault lives: on local desktop vaults, in the self-hosted web app (since 2.29), and, since 2.30, from the desktop app connected to a remote vault, where creating, editing, running, undoing, and run history all delegate to the server's journalled workflow API, with runs prepared client-side and applied transactionally on the server. The server must be 2.29 or newer; older servers stay safely read-only until upgraded. Inside step arguments, {{title}}, {{date}}, {{count}} and any frontmatter field expand per note.
An event run sees only the note that changed: every source (all, folder, tag, search, current) resolves over that one note, so all | contains type: topic | move Topics means “file this note under Topics when it says so”, and nothing is read across the vault on every save. A burst of autosaves while you type is one run, a note you are still typing in waits for its next save, and a run that changed nothing says nothing. trigger: on note-saved where folder = inbox adds a condition in the same field op value form a where step takes. note-moved fires with the new path for a rename, a move, Archive, Trash and Restore; tag-added fires for a save that gave the note a tag it did not have. Only edits made in the app fire: a change that arrives by sync or from another device does not, what a run itself writes never fires again, a folder rename does not fire for the notes inside it, and the phone apps do not fire at all. status: draft or trigger: manual silences one workflow; Settings → Workflows → Event triggers (workflow_event_triggers under [view] in config.toml) silences them all on that device.
ZenNotes gives you several ways to find things, each tuned to a different question: which note, which line, which heading, and what links here. This section brings them together so you can pick the right one and reach it from the keyboard.
Choose by what you are looking for. To jump to a note by name, use the note search palette. To find a word or phrase inside note bodies across the vault, use vault text search. To edit matches in the note you are in, use in-note find and replace. To see which notes point at the current note, use the connections panel. To browse by topic, use the Tags view.
Shortcuts below use Mod to mean Cmd on macOS and Ctrl on Windows and Linux. Vim leader sequences (Space ...) require Vim mode. Every shortcut is remappable in Settings, Keymaps.
Fuzzy-find and open a note by its title or path. Add inline #tag tokens to narrow by tag. Open it with Mod+P (Mod+F when Vim mode is off) or Space f. No match? Shift+Enter opens a New note form with your search as the name, a folder picker and tags; Enter creates the note and opens it.
By name
Full-text search across note bodies in Inbox, Quick Notes, and Archive, line by line. Open it with Space s t or the palette 'Search Text in Vault'. Choose the search engine in Settings.
By content
Search and replace within the current note, with case, whole-word, and regex options. Open it in Edit or Split mode with Mod+F (Cmd+F on macOS, Ctrl+F on Windows and Linux) or F3, which also brings it back with your last search after you close it. With Vim mode off, Mod+F in the main window opens note search instead, so use F3 there, or unbind Search notes in non-Vim mode under Settings → Keymap. The change takes effect in an open pinned reference pane too.
In this note
Jump to any heading in the active note. Open it with the :outline ex command, Space p, or Mod+3 to toggle the outline panel.
By heading
See backlinks and unresolved links for the current note. Toggle it with Mod+2, then navigate and peek with the keyboard.
By link
Browse and filter notes by hashtag, down to the tagged blocks inside each note. Open it with :tag or from the sidebar.
By topic
The note search palette is the fastest way to open a known note. It fuzzy-matches across note titles and paths and returns the 20 best matches; press Enter to open the highlighted result and Escape to close.
Filter by tag inline by typing #tag tokens anywhere in your query. Tokens render as chips, and you can mix text and tags (for example, migration #ops #prod) or search by tag alone. Navigate results with the arrow keys or Ctrl+N and Ctrl+P.
With a #tag in the query, each matching note also lists up to two of its tagged blocks (the list item, paragraph, or heading section carrying the tag), then a +N more tagged blocks row that opens the rest in the Tags view. Enter on a block opens the note at that line, highlighted, and Ctrl+O comes back. Words after the tag narrow the blocks to those containing them, and a note whose matching block sits deep in its body is listed too; a note that matched only by its title stays a plain row. With several tags, notes carry all of them and the blocks carrying all of them come first. Settings, Editor, Search, Show tagged blocks in note search turns this off (tagged_blocks under [search] in config.toml).
Vault text search looks inside note bodies across Inbox, Quick Notes, and Archive, returning line-level matches with the note path, line number, and a highlighted excerpt. Results are limited to the 80 best matches, input is debounced by 120ms, and you can open any match at its exact offset in the editor.
The engine is configurable. In Settings, Editor, set the Vault text search backend to Auto, Built-in, ripgrep, or fzf. Auto detects what is installed and prefers fzf, then ripgrep, then the built-in JavaScript search; an explicit choice overrides auto-detection. A backend indicator in the search UI shows which engine ran. If ripgrep (rg) or fzf are not on your PATH, set an absolute path in the ripgrep binary path or fzf binary path fields; leave them blank to use the binary from your PATH.
Find and replace searches within the note you are editing. It highlights every match in the document, and you can replace one match or all of them. Toggle case sensitivity, whole-word matching, and regex mode with the buttons in the dialog; regex mode supports pattern replacement. The dialog is available in Edit and Split modes, but not in Preview, and your settings persist across sessions.
To move within a long note, open the heading outline palette. It shows the note's headings as a searchable tree with indentation by level and line numbers; fuzzy-filter by heading text and press Enter to jump the cursor there. In Split or Preview, the outline syncs with scrolling so the jump matches the visible location. The outline panel is a persistent, dockable version of the same view.
The connections panel answers what links here. It lists backlinks (other notes that link to the current note through [[wikilinks]] or standard Markdown links like [text](Note.md)) and unresolved links that could be created. A wikilink at a file in the vault, such as an embedded image or a PDF, is listed as a file and opens in its own tab; the panel only offers to create a note for a wikilink that reaches nothing. Toggle it with Mod+2; it lives on the right side of the active pane. Under a note's missing links, the All unresolved links in the vault row opens the Unresolved Links view, the same list for the whole vault.
Navigate the panel with the keyboard: j and k move the selection, gg and G jump to the top and bottom, and Enter or o opens the selected note. Press p to peek a hover preview of the selected connection without leaving the panel, then h or Escape to step back from the preview to the list, and again to return to the editor.
Rest the pointer on a [[wikilink]] in the editor and the link popover opens: the note the link names, in a small floating editor over the note you are in. It is the note itself, not a preview, so what you type there is saved to it like any other edit and shows up in any tab that has it open. Move the pointer away and it closes; click or type in it and it stays until you press Escape or click outside it. A [[Note#Heading]] link opens it on that heading.
A link to a note that does not exist yet offers Create note: press Enter (or click it) and the note is created where gD would put it (in Inbox, named after the link), then opens in the popover ready for its first line, while the note underneath stays where it was.
From the keyboard, put the cursor on a link and press K in Vim mode, or Shift+Mod+K with Vim mode on or off. The popover takes the keyboard: K on a link inside it moves on to that note, Mod+Enter opens the note in a tab, and Escape closes it and puts you back on the link you came from. In Vim mode the first Escape leaves insert mode and the next one closes the popover. To keep the popover to the keyboard only, turn off Settings → Writing → Link popover on hover (link_popover_on_hover under [editor] in config.toml). In the connections panel, p still peeks a read-only preview of the selected backlink.
Link a note before it exists and the Unresolved Links view keeps it for you: every [[wikilink]] in the vault that points at a note that does not exist yet, grouped by the missing note with the most-linked first, and under each one the notes that link to it with the line each link sits on.
A link is listed exactly when the editor draws it as unresolved (muted, with a dashed underline). A heading ([[Note#Heading]]), block ([[Note^id]]) or display-text ([[Note|text]]) link to an existing note resolves, so does a link to a file in the vault or to a .base database, and a [[link]] inside a fenced code block or inline code is text, not a link. Creating a note from the view, from the link popover, or any other way takes its name off the list.
When you want to find notes by topic rather than by word, use the Tags view. It shows every tag in the vault with per-tag counts; select one or more tags to list notes that carry all of them (a Match: Any toggle switches to union), and use the in-view filter to narrow further. Under each note it lists the tagged blocks, the list item, paragraph, or heading section that carries the tag, so an idea jotted among others in one note is found on its own; Enter on a block opens the note at that line. Clicking a #hashtag in a rendered note also opens the Tags view with that tag selected. For the full tag model, including hierarchical tags and renaming or deleting tags across the vault, see Organization.
Templates turn a repeated note shape into one keystroke. Use a built-in or author your own, fill in variables like the date and week automatically, and land the cursor exactly where you want to start writing.
Open the picker, choose a template, pick a destination folder, and name the note. ZenNotes substitutes variables and places your cursor.
Space t
:template
New Note from Template…
Right-click → New from template
A curated starter set for engineering and personal work. Every one is editable: fork it from Settings → Templates to make it your own.
Architecture Decision Record with context, decision, and consequences.
Engineering
A proposal with summary, motivation, design, and alternatives.
Engineering
Reproduction steps, expected vs actual, environment, and severity.
Engineering
Incident review with timeline, root cause, and action items.
Engineering
Dated agenda, notes, decisions, and action items.
Engineering
One-on-one: wins, blockers, growth, and follow-ups.
Engineering
A dated daily log with focus, schedule, tasks, and a log.
Personal
Review last week and plan the next, titled YYYY-Www.
Personal
Notes on a book or article: key ideas, quotes, takeaways.
Personal
A free-form, first-person dated entry.
Personal
Goals, scope, milestones, stakeholders, and risks.
Personal
A simple checklist scaffold.
Personal
Tokens are replaced when the note is created. Unknown tokens are left untouched, so your own braces survive.
Custom templates live as plain Markdown files in
.zennotes/templates/, so they stay portable and
versionable like the rest of your vault.
{{date:YYYY-MM-DD}}, and targetFolder / targetSubpath to set a default destination.
Pick a folder under Settings → Templates → Template folder, or choose
“Use as Template Folder” from a folder’s menu in the sidebar (m
in Vim mode). Every note in it, subfolders included, is a template in
the picker, marked with its folder.
# completion, and its notes out of search, a #tag search included; start a Search Notes query with the folder’s path (Templates/) to find one.Tasks stay plain Markdown, but the app gives them list, calendar, and Kanban workflows on top.
ZenNotes reads unchecked and checked Markdown task list items outside fenced code blocks.
- [ ]
- [x]
Compact vault-wide task scanning for every Markdown checkbox outside fenced code blocks. Open a task to jump to the exact source line. Archived notes retire their tasks from every Tasks surface (un-archiving brings them back, and archiving a note with open tasks asks first); a Settings toggle keeps them visible instead.
Due-date review for scheduled tasks. Waiting and done tasks stay out of normal due-date buckets so the calendar stays focused on active work.
Drag tasks between columns grouped by status, priority, folder, or a custom @status workflow you define. On the Status board a started task ([/]) has its own In progress column between No due date and Waiting: drop a card there (or send it with Shift+L) to mark it [/], and drop it back on Today or Upcoming to reopen it with that date, or on No due date to reopen it without one (that drop clears its due:, and a daily-note task, whose date is its note’s, cannot take it). The board updates immediately, then ZenNotes writes the source Markdown task line asynchronously. Dragging a card to a new spot inside its own column hand-prioritizes it; that arrangement is saved per column and restored when you come back to the board. To have the cards follow their dates instead, set Order in the board's toolbar to Due date (s in Vim mode, :order due on the ex line, or kanban_card_sort = "due" in config.toml): every column on every board, custom status boards included, then sorts by due date, earliest first and cards without one last, and a card dropped into another column lands in its date slot. Your dragged arrangement is kept meanwhile, and Manual brings it back. On a board wider than the window, hold a dragged card or column header near the board's left or right edge and the board scrolls that way, faster the closer you get; a card held near the top or bottom of a long column scrolls the column. After a drop the cursor sits on the card or column you moved, so the keyboard picks up where the mouse left off. For a separate board per project, whose cards are not tasks, use New Kanban (see Make a Kanban board for each project).
One filter box in the Tasks header narrows all three views: the list, the calendar, and the Kanban board, where cards filter out but the columns stay put. Press / to focus it (Vim mode) or run :filter <text> from the ex line; Esc clears it, and the query survives switching views. Matching is a substring check across task text, note titles, tags (#project-beta), !high priorities, and @key:value fields, so tagging tasks with @project:alpha and filtering @project:alpha on the status board gives you a one-project Kanban. A task that is a whole note (made with New task, tags: [task] in its frontmatter) also matches a #tag written anywhere in its body, so you can tag it while you write its notes, where the tag picker helps; a checkbox task matches only the tags on its own line. The header shows how many tasks match, and hand-arranged card order is preserved for the cards a filter hides. A query worth typing twice is worth saving: press Save filter… in the row under the header (or run :savefilter <name>) and it becomes a chip there; click a chip, run :filter <name>, or press F (Vim mode) to pick one from a list, and the command palette lists every saved filter as "Tasks: name" so you can jump to it from any note. Right-click a chip to rename or delete it. Saved filters live in config.toml under [saved_filters], one "Name" = "query" line each, so they travel with your dotfiles and a hand edit applies live.
A bare - [ ], like those a daily-note template leaves, stays out of the Tasks views, the Calendar and Timeline panels and the home view, and a quiet “3 hidden” beside the View button says how many; click it to show them. A task with any text always shows, even just due:2026-11-02. Turn it off with Hide empty tasks in the View menu (v in Vim mode), E in Vim mode, Settings → Tasks, or hide_empty_tasks under [view] in config.toml.
Each view has a Keys button at the right of its toolbar (? in Vim mode) that lists its keys; Esc closes it. With Vim mode off it shows only the keys that work then: the arrows, Enter, Space, Tab and Shift+F10.
Metadata tokens are stripped from the display title but stay in the Markdown line on disk.
Status columns are derived from checkbox state, due date, and @waiting. Dragging between columns rewrites only the affected task line.
“Group by: Folder” gives every note folder its own column, so notes that live together group together with nothing to maintain.
Projects/alpha, Areas, Quick Notes, and so on, system folders first and subfolders alphabetically.:folderroot Projects on the board, or kanban_folder_root = "Projects" in config.toml) and that folder's children become the columns; deeper notes roll up to their child, and notes outside it share an “Other folders” column.Beyond the derived Status columns, the Kanban “Group by” menu has a Custom status board whose columns are a free-form workflow you define.
config.toml under [view], e.g. kanban_statuses = ["backlog", "in_progress", "review", "done"].@status:<id> token, e.g. - [ ] Ship it @status:review. A note-level status: frontmatter key sets a default for that note’s tasks.@status token; the trailing “No status” column clears it.task is a card of its own: its frontmatter status: is its custom status, and without one it sits in “No status” until you move it.status: names one of your Kanban statuses stays in that column, so a done column holds the task notes you finished, still checked.< / > with a column focused; the arrangement is saved per board (the “No status” column stays last).s in Vim mode, :order due, or kanban_card_sort = "due" in config.toml) and every column follows its cards’ due dates instead, cards without one last; Manual brings your arrangement back.[kanban_column_titles] in config.toml). The rename is a display label only: the column still shows its underlying @status:<id> beneath the name, and moving a card into it writes that value, not the label.Column titles are editable display labels. Click the title or pencil icon, rename it, and press Enter or click away to save. Clear the field to reset the default label.
A task’s indented subtasks fold into its card, with a bar reading
3/5 · 60%, counted like the 3/5 chip in the note.
Tab steps onto a card’s subtasks (Shift+Tab back, Esc to the card), with Vim mode on or off. Space (or x in Vim mode) toggles one, and Enter opens the note at its line, where you edit, add or reorder subtasks.
A WIP limit caps how many cards a column should hold. Right-click a
column header and choose “Set WIP limit…”: the header then reads
2 / 3, and past the limit the column turns red, as in 4 / 3.
↑ on a column’s first card reaches its header, where Shift+F10 opens the menu and Enter renames the column.W sets the focused column’s limit, :wip 3 does too, and a bare :wip clears it.[kanban_wip_limits] table of config.toml, such as "status:in-progress" = 3.
Give a column a color: right-click its header and choose “Color…”, then pick
Gray, Red, Yellow, Green, Teal, Blue or Purple. The header gets a dot and a
colored top edge, and the cards’ @field:value chips for that column match it.
Shift+F10 on a column’s header opens its menu. In Vim mode, C opens the colors for the focused column, :color blue sets one, and a bare :color clears it.[kanban_column_colors] table of config.toml, such as "status:in-progress" = "blue".
Split the board into rows by a second field: in the View menu
(v in Vim mode), pick Lanes: Priority, Folder, Tag, or any
@field you use. Each lane is a row across the same columns,
with its own count.
!high, an @sprint lane @sprint:24, and a tag lane makes its tag the task’s first (a task sits in the lane of its first tag; No tag removes them). Folder lanes are read-only, like folder columns.S steps through the lane fields, { / } hop between lanes, Shift+J / Shift+K move the card a lane down or up, za collapses or expands a lane, and zM / zR do all of them. With Vim mode off, the arrows reach each lane’s header, where Enter or Space collapses it.:lanes tag sets them from the ex line, and a bare :lanes turns them off. The choice is kanban_lanes under [view] in config.toml.The practical model for Docker, browser access, desktop-to-server use, and the security posture you get out of the box.
In self-hosted web mode, ZenNotes asks for the server auth token once, then the server issues an HttpOnly, SameSite=Strict session cookie. Refresh should keep working without leaving the token in the URL or browser local storage.
Your notes stay in a normal host folder. Docker mounts that folder into the server container; ZenNotes is serving the host files, not copying them into container-only storage.
Since 2.51.0 the self-hosted Go server lives at github.com/ZenNotes/znserver. It embeds a checksummed build of the web app that the desktop repository publishes, ships as standalone binaries and as the adibhanna/zennotes Docker image, and is released on its own cadence.
The desktop app can connect to the same ZenNotes server the browser uses. Saved Remote Workspaces let you keep multiple servers or vaults ready, change the active remote vault later, and switch back to a local vault cleanly.
Creating or deleting a folder in one client now appears in any other open client sharing the same vault, including the self-hosted web app, without a manual refresh. Empty folders used to show up only on reload.
The server-side vault picker only sees allowed mounted roots. If a folder is not mounted or not inside the configured browse roots, the browser picker and remote desktop flow will not be able to select it.
Note read, write, rename, delete, asset upload, and folder operations all walk each existing path component and resolve symlinks. Any link that points outside the canonical vault root is rejected before any file is touched, so a planted symlink inside the vault cannot be used to read or overwrite host files.
The Go server does not terminate TLS itself. Set ZENNOTES_BEHIND_TLS=1 once a reverse proxy is in front and the server marks cookies Secure and emits HSTS. ZENNOTES_TRUSTED_PROXIES then controls which TCP peers may set X-Forwarded-Proto and X-Forwarded-For so the flags cannot be flipped by an arbitrary client.
POST /api/session/rotate-token replaces the bootstrap token, persists it with mode 0600, and invalidates every existing session. Requires the current token in the body even when authenticated, so a stolen session alone cannot rotate the secret.
New notes default to 0600 and directories to 0700 on Unix hosts; tune with ZENNOTES_VAULT_FILE_MODE / ZENNOTES_VAULT_DIR_MODE if needed. Per-request body limits cap note writes (10 MiB) and asset uploads (50 MiB) so a single bad request cannot fill the disk.
Repeated failed logins from the same client incur exponential backoff (1, 2, 4, 8, 16, 32, 60 seconds). Combined with the 256-bit bootstrap-token entropy, brute-force is not a realistic threat, but the backoff still protects users who set a short manual token.
Notes are written as plain Markdown so any tool can back them up or read them. For VPS-snapshot or stolen-disk threats, layer encrypted backups (Borg, restic) and an encrypted volume (LUKS, ZFS native, APFS encrypted) underneath the vault path. The repo docs include a cookbook for each.
When desktop is using a server-backed vault, ZenNotes shows a Remote badge in the sidebar and title bar, labels copied paths as server paths, and keeps local-only file-manager actions separate from remote workspaces.
Editor behavior, Markdown rendering, slash commands, picker behavior, and most settings come from the same shared app core. The main differences are runtime-specific things like native file dialogs, desktop save-to-PDF, and browser print-to-PDF.
The apps, self-hosted server, terminal tool, and Homebrew tap below are open source. Each repository builds and releases its own component. iOS and Android pin the shared editor packages, the Go server pins a browser bundle, and hosted publishing uses a read-only viewer bundle. The TUI is a separate Go implementation compatible with the same vault files and server API.
The website and hosted Cloud backend are maintained in a private Laravel repository. They handle accounts, billing, sync, backups, and publishing. The public Go server is the self-hosted product, not a deployment of the hosted Cloud service. Desktop, server, mobile, and CLI version numbers advance independently.
The Electron desktop shell, browser client, shared TypeScript editor/domain/contracts, and read-only public share viewer. It publishes editor packages for iOS and Android, the browser bundle for znserver, and viewer artifacts for hosted publishing. The Go server and terminal app have their own implementations and repositories.
Get it: Installers on the releases page, the Homebrew cask, the AUR package zennotes-bin, Nix, and the download links on this site.
MIT
The self-hosted server. A Go API that serves your vault to the browser app and to remote desktop connections, with a pinned, checksummed build of the web app embedded. It releases on its own cadence.
Get it: Standalone binaries for Linux, macOS and Windows on its releases page (with SHA256SUMS), and the multi-arch adibhanna/zennotes Docker image.
MIT
An independent Go implementation: zn for shell commands, zn tui for the terminal editor, and zn mcp for AI assistants. Works with local folders or the self-hosted server, without the desktop app or Node.js. Desktop 2.81.0 bundles Go CLI 0.14.0 on macOS and Linux and installs newer signed CLI releases on its own, so CLI fixes do not wait for a desktop release.
Get it: Archives for six targets on its releases page, or brew install zennotes/tap/zn.
MIT
The iPhone and iPad app: a Capacitor shell around pinned shared editor packages, with native file access, iCloud integration, and ZenNotes Cloud sync. It builds without cloning the desktop repository.
Get it: Source on GitHub; install npm dependencies, sync the iOS project, and build with Xcode as described in its README.
MIT
The Android Capacitor shell around pinned shared editor packages, with app storage, user-selected folders through Android's Storage Access Framework, and ZenNotes Cloud sync. It builds without cloning the desktop repository.
Get it: Source on GitHub; install npm dependencies, sync the Android project, and build with Android Studio or Gradle as described in its README.
MIT
The Homebrew tap: the zennotes cask for the desktop app and the zn formula for the command-line tool.
Get it: brew install --cask zennotes/tap/zennotes and brew install zennotes/tap/zn.
MIT
Every binding is remappable in Settings. Mod is ⌘ on
macOS, Ctrl on Windows and Linux.
These work across the main app shell. With Vim mode on and the editor focused, an app shortcut on a Ctrl chord wins over Vim's own use of that chord, except the ones Vim mode keeps on purpose: Ctrl+W (the pane prefix), Ctrl+O and Ctrl+I (the jumplist), and Ctrl+D and Ctrl+U (half-page scroll). On macOS these shortcuts use Cmd and never collide.
These apply inside the floating capture window, opened with the quick capture hotkey.
The primary keyboard-first movement patterns. The Vim-style ones assume Vim mode is on.
Inline completions that appear while you type in the Markdown editor.
These keys apply when reading preview content or the connections panel.
Keys for a CSV database table while its grid has focus; the grid takes them before any global motion. The single-letter keys (h / j / k / l, H / L, 0 / ^ / $, g g / G, i, x, o, O, c, m, a, d d) and Ctrl-o / Ctrl-w belong to Vim mode, like every list in the app. With Vim mode off the arrows, Enter, Space, Esc, Delete / Backspace and Shift+F10 (or the Context Menu key) stay live, and the rest is in the row and column menus, the header buttons and the command palette.
Keys for a database Board, a Kanban made with New Kanban included, while the board has focus. They match the Tasks Kanban board. The letters belong to Vim mode; with Vim mode off the arrows, Enter and Shift+F10 (or the Context Menu key) do the work, and the card menu moves cards.
Run any of these from the : prompt. Tab on the ex line completes commands and supported arguments.
:w
:set [no]statusbar
:harper [on|off]
:unbind action.id
:bind <keys> command.id
:ignorekey <key>
:filter <text or name>
:savefilter <name>
:delfilter <name>
:wip <limit>
:color <name>
:lanes <field>
:q
:wq
:format
:cover [image]
:imgwidth {px}
:tasks
:template / :tmpl
:version / :ve
:daily
:weekly
:monthly
:tag foo bar
:trash
:split / :vsplit
:edit path / :e path
:new [path]
:move [folder] / :mv
:bn / :bp
gt / gT
{count}gt / {count}gT
{count}[b / {count}]b
:buffers / :ls
:bd / :bc
:only
:closepanel / :closep
:qa / :quitall / :xa / :wqa
:wa / :wall
:help / :h
:demo_generate / :demo_remove
:cmd query / :commands
:tab_menu / :tab_close_others / :tab_close_right
gd
gD
K
⌘L / Ctrl+L
<Tab> on the ex line
<Space> l f
<Space> l y
<Space> (pause)
<Space> o
<Space> f
<Space> e
<Space> p
<Space> u
<Space> G
<Space> k
<Space> t
<Space> i
<Space> q
<Space> c
<Space> n
<Space> l s
<Space> l c
<Space> l u
<Space> l a
<Space> l l
<Space> d
<Space> w
<Space> m
:outline
:repeat [rule|off]
:remind [when|off]
:timeline
:gallery [folder] / :gal
:kanban [folder] / :kanb
:unresolved / :unres
:view edit|split|preview
:zen [toggle|on|off]
:editmode / :splitmode / :previewmode
:fold / :unfold
:foldall / :unfoldall
zn is the Go command-line tool from
ZenNotes/tui.
It works with local vault files or a self-hosted ZenNotes server.
Script note, task, folder, comment, and database operations; use
zn tui for the terminal editor or zn mcp
for an AI assistant. Data commands support --json.
The CLI runs independently of the desktop app; zn open
uses the desktop app when you want to open a note there.
On macOS and Linux, desktop 2.51.1 and later bundle the Go CLI. Open Settings → CLI and click Install. Settings shows the chosen writable directory, command path, and any PATH change or administrator permission required. The Go runtime stays in app data, so it survives an AppImage closing or moving. It does not need a system Node.js or Go installation.
For an independent installation on macOS or Linux, run
brew install zennotes/tap/zn. Windows users should
install the standalone zn.exe; the desktop Settings
installer does not support Windows. Downloads for all three
operating systems are on the TUI
installation page.
ZENNOTES_VAULT overrides the resolved vault root, useful when scripting against a non-default vault.--no-color and the NO_COLOR environment variable disable ANSI color in the help output.zn --help for the live command list, or zn --version for the CLI version.
Desktop 2.81.0 bundles CLI 0.14.0. Run zn tui to open
the terminal app, or just zn in an interactive terminal.
An existing desktop-managed CLI keeps itself up to date (see below).
Your commands and shortcuts keep working; Settings shows the
installed version and offers Repair if needed.
Homebrew and manual installations stay managed by their own installer.
Stale shortcuts from a moved Mac app or an old AppImage offer
Repair shortcut. Review the old target, replacement
and backup path before repairing.
CLI 0.12.2 includes editable settings, restored splits and sessions,
comments, attachments, templates, bulk actions, and cross-note yank
and paste. In the TUI, :version opens a persistent report;
press c or y to copy it. Use
zn status, zn doctor, zn config,
and zn completion for setup and scripts.
zn server and :servers manage native local
servers. zn vault list marks each entry app
(saved by the desktop app) or terminal (saved by zn), so
zn use, zn disconnect and
zn vault remove say which one they act on.
Since 0.7.0, zn mcp keeps what a note said before an
assistant changed it, for the review in the desktop app. 0.7.1 leaves
cancelled tasks out of the open ones in zn task list and
list_tasks, and when a server needs a token, it points to
Settings → MCP → Server token in the desktop app. 0.7.2 reads tasks in
numbered lists and quotes the way the app does, and 0.8.0 adds
zn task watch, which prints each task status change as it
happens, and gives each task’s status in zn task list --json
and list_tasks. 0.8.1 keeps a finished task note in its
Custom status column and gives zn mcp the desktop app’s
assistant instructions again, and 0.9.0 follows the vault’s Task folders
in zn task list, zn task watch and
zn mcp, and saves both Tasks folder lists from the TUI’s
Settings where every app reads them. 0.9.1 keeps a wikilink of more
than one word from widening the TUI preview’s row and scrolling the
whole screen. 0.9.2 lets a second $ on a wrapped line
reach the end of the line and makes three backticks a code fence,
0.10.0 adds zn base pages, which gives every database
record its record page so each can be linked, and 0.11.0 gives a task
without a due date its own No due date group and Status board column,
as the desktop app does, and orders the task list by priority with
O or :order priority. 0.12.0 can draw
display math and TikZ in the TUI preview with
[terminal] math = "latex", using TeX installed on your
computer (zn does not include TeX; zn doctor prints the
install commands), 0.12.1 fits pictures in the preview to the pane
as it grows or shrinks, 0.12.2 says which TeX tool is missing
and how to install it, and 0.13.0 lets zn mcp share only
part of a vault (--allow-path, --deny-path,
--read-only, --access), keeps assistants out
of hidden and system folders, and puts a row zn base add
makes into the picked rows of the view the database opens on, so it
shows up there as one added with + Row does; 0.13.1 leaves the
template folder out of tasks, search and tags, as the app does, and
0.14.0 adds month, week and day views to the TUI’s Tasks calendar, a
bar cursor while you type, a note’s own view mode from its frontmatter,
and opens every new note in the editor.
zn update --check shows the latest CLI release. See the
full CLI manual for commands and examples.
Updates arrive without a ZenNotes update. For a zn
installed from Settings → CLI, ZenNotes checks the latest zn release
once a day and installs it when it is newer than the zn you have. Every release carries a manifest signed
with the ZenNotes release key: ZenNotes checks that signature and the
download's checksum, then runs the new zn once to confirm it answers
before switching to it, so a failed or tampered download never
replaces a working CLI. The zn a ZenNotes build ships is its floor: a
newer release stays installed across restarts, and a ZenNotes update
that ships something newer takes over. A release that needs a newer
ZenNotes waits until you update ZenNotes. Turn off
Update zn automatically in Settings → CLI → Updates to
be told instead; Check for updates there, or
Check for zn Updates… in the command palette, checks
right away. A zn installed with Homebrew, Go or by hand keeps updating
through its own installer (zn update).
Desktop-installed commands follow the desktop workspace. Standalone
commands use the terminal default, which you can choose with
zn use. zn tui also uses that terminal
selection unless you pass --workspace-source app.
Explicit --vault and --server flags still
win. Use --workspace-source app|terminal to select the
source for other commands, or set ZENNOTES_WORKSPACE_SOURCE.
During the desktop transition, ZENNOTES_CLI_ENGINE=legacy
selects the previous Node CLI, which requires the original app
resources to remain available. A failed Go command is not retried
automatically through the legacy engine.
Updated desktop and Go CLI builds preserve creation dates through
atomic saves using small files under .zennotes/note-metadata.
Markdown stays unchanged. Keep the .zennotes directory
with vault backups. Older clients continue using filesystem dates.
zn list
--folder <f> --tag <t> --limit <n> --json
zn read <path>
--pretty --style <name|json> --meta --json
zn create
--title <t> --folder inbox|quick|archive --subpath <p> --tag <t> --body "..."|-
zn write <path>
--body "..."|-
zn append <path>
--body "..."|-
zn prepend <path>
--body "..."|-
zn rename <path>
--to <new title>
zn move <path>
--folder <f> --subpath <p>
zn archive <path>
zn unarchive <path>
zn trash <path>
zn restore <path>
zn delete <path>
--yes
zn duplicate <path>
zn base list
--json
zn base create <title>
--folder <f/sub> --json
zn base rows <base>
--json
zn base get <base> <row>
--json
zn base add <base>
--set Field=Value ... --body <text|-> --page --json
zn base set <base> <row>
--set Field=Value ... --json
zn base pages <base>
--dry-run --json
zn search <query>
--limit <n> --json
zn search-title <q>
--json
zn backlinks <path>
--json
zn folder list
--json
zn folder create <p>
zn folder rename <p>
--to <newPath>
zn folder delete <p>
--yes
zn tag list
--json
zn tag find <tag>
--limit <n> --json
zn task list
--unchecked --all --tag <t> --include-excluded --json
zn task toggle <id>
zn task watch
--interval <s> --include-excluded --json
zn setup
zn init [folder]
--name <n> --no-default --json
zn vault add <folder>
--name <n> --no-default --json
zn connect <url|name>
--name <n> --token <t> --no-default --json
zn use <name|folder|url|app>
--json
zn vault info
--json
zn vault list
--json
zn capture "..."
--folder <f> --tag <t> --title <t> --json
zn open <path>
-n, --new-window
zn tui [path]
--vault <v> --server <s> --workspace-source app|terminal
zn mcp
--vault <v> --server <s> --token <t> --allow-path <p>… --deny-path <p>… --read-only --access read|comment|write
--vault <name|path>
--server <name|url>
--token <token>
--workspace-source <app|terminal>
--json
ZENNOTES_VAULT
ZENNOTES_SERVER
ZENNOTES_REMOTE_TOKEN
ZENNOTES_CONFIG_DIR
ZENNOTES_WORKSPACE_SOURCE
Common one-liners. Pipe stdin into capture,
append, prepend, create,
or write with --body -.
$ zn capture "Meeting takeaways" --tag work
$ pbpaste | zn append inbox/Daily.md --body -
$ zn search "deadline" --json | jq '.[].path'
$ zn list --tag idea --limit 5
$ zn task list --unchecked --tag work
$ zn task watch --json | jq -c 'select(.status == "ready")'
$ zn list --server home
$ zn capture "from CI" --server https://notes.example.com
$ zn tui --workspace-source app
$ zn --workspace-source terminal vault info --json
zn mcp runs the Go MCP stdio server. Desktop's managed
Claude Code, Claude Desktop, and Codex integrations prefer its
managed CLI when it was installed from Settings → CLI; otherwise,
a zn installed some other way included, they use the
bundled Electron/Node runtime. The Claude desktop app's Code tab
runs Claude Code, so it reads the Claude Code (CLI + Desktop Code
tab) entry; Claude Desktop (Chat) reaches only its Chat tab.
Existing mcp.js integrations
remain on that legacy runtime until reconfigured. Since 2.54 the
bundled runtime takes the same --vault,
--server and --token flags as the Go CLI,
so zn mcp --vault work in a client config points that
assistant at another vault while the desktop app stays on its own;
a --vault that does not resolve is reported on stderr
(which the client logs) and the server still starts.
Go MCP uses the same workspace selectors as other CLI commands and
resolves the workspace again before every tool call, so it follows
the desktop when you switch vaults. A switch never redirects work
silently: the assistant's next tool call is refused with a note naming
the old and the new vault, and once vault_info confirms
the switch, the calls after it run in the new vault. The bundled
runtime follows switches the same way. Either runtime takes a server
token from --token, ZENNOTES_REMOTE_TOKEN,
or the token saved for that server's URL in credentials.toml
(the bundled runtime since 2.69). The desktop keeps its own copy in
the OS secret store; to hand it to agents without a token in their MCP
config, choose Let assistants use it under Settings → MCP → Server
token (since 2.69), or run zn connect <server-url> --no-default
once. Both write that same file, and the assistant's next call uses
it. Any program running as you can read the file, so sharing is
opt-in: Stop sharing removes the token, forgetting the server in
Settings → Vault removes the copy the app wrote, and a new token saved
for the server in the app replaces it.
vault_info reports primaryNotesLocation and an inboxAbsolutePath so assistants pick the right folder for new notes. An assistant given part of the vault never sees where the vault lives on disk; vault_info lists what was shared under access instead.--allow-path, --deny-path, --read-only and --access (zn 0.13.0 and desktop 2.80.0) to share only part of the vault, enforced on every tool; see MCP and AI assistants, Share part of a vault with an assistant.path is canonical: never prefix inbox/ yourself when the vault is in root mode.ZenNotes ships a local Model Context Protocol (MCP) server so AI assistants (Claude Code, Claude Desktop, and Codex) can read and write your vault directly. Manage it in Settings → MCP (desktop).
The MCP server exposes note, task, comment, and database operations to compatible assistants. Run zn mcp from either a standalone Go CLI or the desktop-managed command. It can use a local vault or a self-hosted server; it is not a ZenNotes Cloud login client.
Both MCP servers, Go zn mcp and the one bundled with the desktop app, resolve the workspace again before every tool call, so an assistant that is already connected follows a vault switch without a restart: a switch in the desktop app, or zn use for a standalone zn. A switch never redirects work silently: the assistant's next call is refused with a note naming the old and the new vault, and once vault_info confirms the switch, its calls run in the new vault. To keep an assistant on one vault, give it --vault or --server; Go zn also takes --workspace-source app|terminal.
Open Settings → MCP to see the server status (Ready, Not built, or Checking), reveal the exact launch command, connect clients, and edit the system prompt sent to assistants.
One-click install writes a managed ZenNotes entry into each client config. Uninstall removes only that entry.
Launch flags limit what an assistant can see and do, on every ZenNotes tool (ZenNotes/tui#21).
An assistant connected through MCP sees the whole vault unless its launch flags say otherwise, and the server enforces them on every tool: listings, search, tags, tasks, backlinks, assets, comments and error messages, so a hidden note cannot be found another way. --allow-path <path> shares only that folder or note and what is inside it (repeat it for more), --deny-path <path> hides one even inside an allowed folder, --read-only offers the reading tools only, and --access comment adds the comment tools to them. Paths are vault-relative, as the tools report them: Projects in a vault that keeps notes at its root, inbox/Projects in one with an Inbox folder, and a system folder you moved under its own name (99 Archive/Projects shares that folder's archived notes). A path covers the folder and everything below it, never a sibling that only starts with the same letters, and case and accents do not matter. zn mcp (zn 0.13.0 and later) and the server bundled with the desktop app (2.80.0 and later) take the same flags and give the same answers; add them after the command in the client's config, for example "args": ["mcp", "--allow-path", "Projects", "--read-only"]. Settings → MCP then shows that client as Needs update, and updating it there removes the flags.
What the assistant gets: a hidden note answers exactly like a missing one (Note not found), and so do paths through a symbolic link, case variants and the .zennotes folder. Its errors and vault_info never show where the vault lives on disk, and vault_info lists what was shared under access. Tools it cannot use are not offered, and empty_trash never is once paths are restricted, since it would delete trashed notes it cannot see. New notes, moves and restores land only inside allowed folders, never through a symbolic link; archiving or trashing a note it can see is allowed even when the archive or trash is not shared, and the note then leaves its view. A folder is renamed or deleted as a whole only when nothing inside it is hidden. Renaming a note rewrites [[links]] only in notes the assistant can see with zn mcp, and in none with the bundled server; on a self-hosted ZenNotes server, which rewrites links in every note, an assistant that sees part of the vault cannot rename notes. A --deny-path that names nothing in the vault (renamed outside ZenNotes, or meant for another vault) shares nothing at all until it is fixed, so a rename never quietly reveals what it hid; the MCP server's log, which the client keeps, names the entry.
The flags govern the ZenNotes tools only. An assistant that can also run commands or read files (Claude Code, Codex, OpenCode) can still read the vault from disk.
Use these MCP tool names to read, search, create, edit, organize, and manage tasks.
When an assistant changes a note through MCP, ZenNotes keeps what the note said before, so you can see each change and keep it or put the old text back. On by default; Settings → MCP → Review agent edits turns it off.
On macOS, ZenNotes can install a Raycast extension so you can search and act on notes without opening the app. Install it from Settings → CLI → Raycast.
ZenNotes copies the bundled extension into app data, installs its dependencies, builds it, and imports it into Raycast.
Raycast’s “Search Notes” command lists notes and offers actions on the selected note.
On macOS, select a Markdown file in Finder and press Space: Quick Look shows it the way ZenNotes renders it, with an Open in ZenNotes button.
The preview uses the app's own Preview, so a note reads the same in Finder as in ZenNotes.
Keys work once you click into the preview; the Vim keys follow Vim mode in your settings.
Every setting in ZenNotes, grouped by panel.
Your portable preferences live in one plain-text TOML file you can read, hand-edit, and sync across machines. Desktop app only: the web app keeps its settings in the browser.
A trimmed example. The real file lists every option (with allowed values) every keymap action (defaults commented out) and every command palette command.
# ZenNotes configuration: portable preferences (theme, editor, vim,
# keymaps, …) you can sync across machines with git, stow, or chezmoi.
# Safe to hand-edit; changes apply live, no restart. Every option is listed
# with its allowed values; a removed option reappears with its default.
config_version = 1
[vim]
enabled = true # true | false: CodeMirror Vim bindings
insert_escape = "" # key sequence to leave insert mode, e.g. "jk"; empty disables
yank_to_clipboard = false # also copy Vim yank/delete/change to the clipboard
[search]
backend = "auto" # auto | builtin | ripgrep | fzf
ripgrep_path = "" # absolute path to ripgrep; empty = look on $PATH
tagged_blocks = true # with a #tag in Search notes, list the tagged blocks under each note
[editor]
live_preview = true # hide markdown syntax on inactive lines
render_tables = true # render tables as widgets in live preview
detect_code_languages = true # guess the language of a code block that names none, and highlight it; never written to the note
font_size = 16 # editor + preview font size (px)
math_font_scale = 100 # math size as a percentage (50-200); scales $…$ and $$…$$
line_height = 1.65 # line-height multiplier
word_wrap = true # wrap long lines vs. scroll horizontally
# … more editor options …
[appearance]
theme_family = "gruvbox" # apple | gruvbox | catppuccin | github | nord | tokyo-night | kanagawa | …
theme_mode = "dark" # light | dark | auto
[typography]
text_font = "" # editor + preview font; empty = system default
mono_font = "" # code / monospace font; empty = system default
[view]
tasks_view_mode = "kanban" # list | calendar | kanban
calendar_week_start = "monday" # monday | sunday | locale
kanban_card_sort = "manual" # manual | due: cards in a Kanban column keep the order you drag them into, or follow their due dates
kanban_lanes = "none" # none | priority | folder | tag | field:<key>: a second field that splits the Kanban board into lanes
hide_empty_tasks = true # leave blank checkboxes out of the Tasks list, calendar and board
task_reminders = true # notify for tasks with @remind
task_reminder_time = "09:00" # when @remind:1d and other reminders without a time fire
# … more view options …
# Keymap overrides. Uncomment a line and edit the binding to remap.
# Binding syntax: "Mod+P" = Cmd/Ctrl+P, "Shift+Mod+K", "Ctrl+W", "Space",
# or a two-key sequence like "g g".
[keymaps]
"global.focusPaneLeft" = "Ctrl+H" # an active override
# "global.commandPalette" = "Shift+Mod+P" # Open command palette
# "global.modePreview" = "Mod+6" # Switch to preview mode
# "tasks.moveTaskUp" = "K" # Move task up
# … every action is listed, defaults commented out …
# Keys for command palette commands; every command starts unbound.
[keymaps.commands]
"note.trash" = "Mod+Backspace" # a chord
"note.archive" = "Leader x a" # a leader sequence, Vim mode on
# "note.restore" = "" # Note: Restore Note from Trash
# … every command is listed, commented out …
# Rename the built-in folders (inbox, quick, archive, trash).
[folder_labels]
# inbox = "Notes"
# Kanban column titles, keyed by "<groupBy>:<columnId>".
[kanban_column_titles]
# "status:todo" = "To Do"
# Kanban WIP limits (1 to 999), keyed by "<groupBy>:<columnId>".
[kanban_wip_limits]
# "status:in-progress" = 3
# Kanban column colors, keyed by "<groupBy>:<columnId>".
[kanban_column_colors]
# "status:in-progress" = "blue"Theme ZenNotes with your own CSS: author a full theme, or layer a small override on top of any theme. Both are plain files under ~/.config/zennotes/ and apply live, no restart.
A theme is a complete palette you select under Settings → Appearance → Custom. An override is a small CSS file that layers on top of whichever theme is active, toggled on or off under Settings → Appearance → Overrides.
Reach for a theme to design a whole look; reach for an override to change one or two things (a different accent, a darker background) without forking a theme.
Settings → Appearance → Custom → New theme scaffolds a folder at ~/.config/zennotes/themes/<name>/ with a manifest.json and a theme.css, reveals it, and adds a card you click to apply. Edits to theme.css apply live.
Only the active theme's CSS is loaded, so you write unscoped selectors: put light or shared values under :root, and dark-mode overrides under :root[data-theme-mode="dark"]. You never put the theme name in a selector. Colors are space-separated RGB triplets, e.g. --z-accent: 255 59 48; (= #ff3b30).
:root {
--z-bg: 255 255 255; /* space-separated RGB triplets */
--z-bg-softer: 245 245 247;
--z-fg-1: 29 29 31;
--z-accent: 0 122 255;
}
:root[data-theme-mode="dark"] {
--z-bg: 28 28 30;
--z-fg-1: 255 255 255;
--z-accent: 10 132 255;
}
/* Optional: bundle a font next to theme.css and point a token at it */
@font-face {
font-family: "My Font";
src: url(zen-theme://my-theme/my-font.woff2) format("woff2");
}
:root { --z-text-font: "My Font", ui-sans-serif, sans-serif; }The seeded overrides/example.css lists them all with copy-paste recipes.
An override is a .css file in ~/.config/zennotes/overrides/, toggled under Settings → Appearance → Overrides. Enabled overrides inject on top of the active theme in filename order, so they win the cascade. Target :root[data-theme] { … } so the rule beats both built-in and custom themes.
Because they sit on top, one override re-themes everything: :root[data-theme] { --z-accent: 255 59 48; } turns the accent hot pink on every theme. Overrides stack, so keep several small ones and flip each independently. The seeded example.css is a commented cookbook with the full token list and ready-to-uncomment recipes.
Bundle an asset with a theme by dropping the file in the theme folder and referencing it with the zen-theme:// scheme, where the host is the folder name: url(zen-theme://my-theme/display.woff2). Remote http/https URLs are never loaded, so themes stay self-contained and work offline; small images can also be inlined as data: URIs.
To find which token or class controls an element, use the Developer tools button in Settings → Appearance → Overrides and inspect it.
Inline comments
Highlight a passage in any note and leave a comment anchored to the text. Press Mod+Alt+M (or open the text menu with m) to start a comment, and Mod+Shift+C to toggle the panel itself. Comments live in a side panel on the editor and stay attached to their selection as the surrounding paragraph evolves.
Anchored to the selection
Each comment stores the selected range plus the text snippet itself. If the surrounding paragraph drifts, ZenNotes re-locates the anchor by snippet so the comment never points at the wrong place.
Side-of-line markers
A small marker sits inside the editor's right padding next to the line that owns the comment. Click it (or click the card in the sidebar) to jump back to the anchored text.
Resolve when done
Resolved comments stay in the note's history but disappear from the active sidebar. Reopen the panel anytime to revisit them.
Plain-file friendly
Comments are persisted next to the note, so the Markdown source itself stays clean and diff-friendly. Your
.mdfiles don't grow comment clutter.Keys in the panel
In the panel, move with j / k and use a to reply, e to edit, r to resolve, and d (or Backspace / Delete) to delete. Deleting from the keyboard asks first, since a deleted comment cannot be brought back; the card’s own Delete button does not ask. With Vim mode off the letters are off: the arrows move, Enter or → jumps to the comment’s text, Backspace or Delete deletes after the same confirm, and the card’s buttons do the rest.
Threads, with names
Press a on a comment (or its Reply button) to answer under it. Each comment names who wrote it, so a note can be discussed the way a pull request is: comment, answer, resolve.
Review with an assistant
Over MCP, an assistant reads a note's threads (
list_comments), answers in them (reply_to_comment), starts new ones anchored to a passage (add_comment) and resolves them (resolve_comment), each signed with its name so its replies stand apart from yours.zn commentdoes the same from a terminal.