Skip to content

get-started-desktop.md

Latest commit

 

History

History
266 lines (168 loc) · 7.56 KB

get-started-desktop.md

File metadata and controls

266 lines (168 loc) · 7.56 KB
Raw

Get Started on Desktop

This tutorial is for someone opening ZenNotes for the first time on desktop and wanting to understand the basic workflow without setting up a server.

By the end, you will have:

  • opened or created a vault
  • created notes and folders
  • used the sidebar, tabs, and editor
  • understood the system folders
  • changed a few important settings

Before you start

You need:

  • the desktop app installed from a release
  • or the repo checked out locally with dependencies installed

If you are running from source:

npm ci
npm run dev:desktop

1. Open a vault

When ZenNotes starts on desktop, it expects a vault directory.

A vault is just a normal folder on disk that contains your Markdown notes and the small amount of metadata ZenNotes needs for UI behavior.

Choose a folder:

  • use an empty folder if you want to start fresh
  • use an existing Markdown notes folder if you want to bring your current notes into ZenNotes

ZenNotes reads and writes normal .md files directly in that folder.

2. Learn the default layout

By default, ZenNotes starts with a lifecycle-oriented layout:

  • inbox/ for your main notes
  • quick/ for quick capture
  • archive/ for archived notes
  • trash/ for soft-deleted notes

If you prefer an Obsidian-style flat vault, you can later switch the primary notes area from Inbox to Vault root.

That setting changes how ZenNotes surfaces the vault in the sidebar. It does not turn your notes into a database or move them into a proprietary store.

3. Create your first note

Use any of these:

  • the + button in the sidebar
  • the command palette
  • the new-note shortcuts you have configured

ZenNotes opens the new note in a tab immediately. Notes are normal Markdown files, so typing into the editor is writing plain text to disk.

Important behavior:

  • there is no hidden note database
  • the note content on screen is the file content on disk
  • if the file changes outside ZenNotes, the watcher can update the UI

4. Use the sidebar

The sidebar is the main navigation surface.

Top area:

  • Search
  • Tasks
  • Quick Notes
  • Archive
  • Trash

Main tree area:

  • your primary note folders and notes
  • optional tag section
  • folder icons, custom labels, and collapse state

Recent versions of ZenNotes also allow:

  • moving Archive and Trash to the top utility area
  • hiding sidebar arrows
  • customizing folder icons
  • naming Quick Notes with a prefix
  • selecting multiple notes or folders with Cmd/Ctrl-click and Shift-click
  • opening images, SVGs, PDFs, videos, audio, and other media inside ZenNotes tabs instead of leaving the app

5. Understand tabs and panes

ZenNotes is designed around keeping context.

You can:

  • keep multiple note tabs open
  • split the current note into another pane
  • open pinned reference panes
  • switch between edit, split, and preview modes

Desktop builds also support:

  • floating note windows
  • native menu integration
  • app updates through the desktop updater
  • direct PDF export of the current note

6. Learn the note modes

The editor stack has three main ways to work:

  • Edit: write directly in the CodeMirror editor
  • Split: see editor and rendered Markdown together
  • Preview: see rendered Markdown only

ZenNotes is keyboard-first, so the app assumes that preview is part of the main writing workflow rather than a secondary export view.

7. Try Quick Notes

Quick Notes are fast-capture notes that live in the quick/ area by default.

They are useful for:

  • temporary notes
  • scratch ideas
  • things you want to rename or move later

You can control how Quick Notes are named from Settings:

  • whether they use a full timestamp or only the date
  • an optional prefix

If the prefix is blank, ZenNotes can create bare timestamp-style filenames instead of forcing Quick Note ....

8. Try search, tags, and tasks

ZenNotes includes several built-in views:

  • Search
  • Tasks
  • Archive
  • Trash
  • Quick Notes
  • Tags

Tasks are extracted from Markdown task list syntax:

- [ ] Ship the onboarding checklist due:2026-04-30 !high #docs
- [ ] Wait for design sign-off @waiting
- [x] Publish the changelog

The Tasks tab has three modes:

  • List for a compact vault-wide task list
  • Calendar for tasks grouped by due date
  • Kanban for moving tasks between status or priority columns

Clicking a task opens the source note at the exact task line and briefly highlights it.

In Kanban mode, drag a card to another column to update the task line. Column titles are display labels: click a title or pencil icon to rename it, press Enter to save, and clear the title to reset it.

For the exact task metadata and Kanban rules, read the Tasks Reference.

Tags come from hashtags in note content and can appear in the sidebar and related views.

Text search can use:

  • the built-in search backend
  • ripgrep
  • fzf

depending on your settings and what is available on your machine.

Picker navigation also supports keyboard-first movement:

  • ArrowDown / ArrowUp
  • Ctrl+N / Ctrl+P

That applies to the command palette, note search, buffer picker, outline picker, and vault text search picker.

9. Try exporting a note as PDF

Open a note and run:

  • Export note as PDF... from the command palette
  • or the configured shortcut, which defaults to Shift+Mod+E

On desktop, ZenNotes renders the note as Markdown and exports it on a white paper-style background instead of exporting the raw editor surface.

10. Install the CLI if you want terminal or Raycast workflows

Open Settings -> CLI and click Install.

ZenNotes installs the bundled zen wrapper into a usable PATH location. It prefers a user-writable directory and only falls back to an admin prompt when no writable PATH location is available.

After install, try:

zen list
zen read "inbox/Project.md"
zen read --path "hellointerview/system design.md"
zen search "deadline" --json

Quote note paths that contain spaces, or pass them with --path.

On macOS, the Raycast extension uses this CLI to search notes and uses ZenNotes deep links to open notes in the main app or a floating window. Install it from the Raycast Extension section on the same Settings -> CLI page. See Use ZenNotes with Raycast on macOS.

11. Adjust the vault model if needed

Open Settings -> Vault.

The most important vault setting is:

  • Primary notes location

Options:

  • Inbox
  • Vault root

Choose Inbox if you want ZenNotes' original lifecycle-first structure.

Choose Vault root if you want the app to surface top-level vault files and folders directly, which is often better for existing Obsidian-style vaults.

You can also configure:

  • system folder labels
  • daily notes behavior
  • daily notes directory
  • folder icons

12. Understand what ZenNotes stores

ZenNotes stores notes in your vault as plain Markdown files.

It also stores a small amount of app/vault metadata under .zennotes/.

That metadata is for things like:

  • vault behavior
  • layout preferences that belong to the vault
  • server-side indexes or runtime state where applicable

The important boundary is:

  • note content is yours, on disk, as files
  • ZenNotes behavior is layered on top of those files

13. Where to go next

Now that you know the desktop basics, read one of these: