Getting started with Zettly

Zettly is a local-first knowledge studio for the kind of thinking that doesn’t fit into a single app. It gives you one vault — a folder of real files on your machine — and six surfaces that all read from the same source. Notes for writing, boards for spatial thinking, decks for presenting, a graph for seeing connections, tasks for getting work done, and a calendar for planning time. No account. No cloud landlord. No lock-in.

If you’ve used tools like Obsidian, Logseq, or Notion, some of this will feel familiar. Where Zettly is different is the way the surfaces talk to each other: a note you drop on a board is the same note, not a copy. A task you write in a meeting note rolls up into the task hub. A slide you build from a board updates when the board does. Everything stays connected because everything shares the vault.

This page is the tour. Read it once, then poke around — most of what you need is one click away from the sidebar.

What “local-first” means in practice

Your vault is a folder on your disk. Notes are plain Markdown files. Drawings are real files too (a structured format you can inspect, back up, and version-control). Zettly watches the folder and keeps its in-app view in sync, but the folder is the source of truth — open it in Finder, sync it with Dropbox, or back it up with anything you trust.

You don’t sign up for anything. You don’t need a network connection. You don’t need to “export” your data because your data is already in a portable, human-readable form on your machine. The app is a window onto your vault, not a cage around it.

This has practical consequences:

• Backups are easy. Copy the folder. You’re done.
• Sync is your call. Use iCloud, Syncthing, Dropbox, Git — whatever you already trust. Zettly doesn’t have an opinion.
• Portability is real. If you stop using Zettly, you still have a tidy folder of Markdown and structured files. Nothing is trapped in a proprietary database.

Create or open a vault

When you launch Zettly for the first time, you’ll be asked to either create a new vault or open an existing folder. A vault is just a directory. Pick any location — Desktop, Documents, a folder inside your cloud sync, a USB drive. The app will create the structure it needs and drop you into a fresh note.

If you already have a folder of Markdown notes, point Zettly at it. The app will treat your existing files as notes without modifying them, and you can start linking and organizing right away. There’s no import step and no conversion — Markdown is Markdown.

You can have multiple vaults and switch between them from the sidebar. Most people only need one, but the option is there.

The six surfaces

Zettly is organized around six surfaces, each designed for a different kind of work. They share the same vault, so anything you create in one surface is available in all the others.

• Notes — Markdown pages with a hybrid editor. Switch between text mode (Markdown with live preview) and draw mode (pressure-sensitive ink, shapes, connectors) on the same page. This is where most of your writing lives. See Notes & editing for the full tour.
• Boards — Infinite canvas surfaces for spatial thinking. Drop live widgets onto the board — notes, task lists, calendar views, graph views — and wire them together with shapes, connectors, and ink. See Boards.
• Decks & presentations — Slide decks built from vault content. Every slide is a canvas scene, so the same drawing tools you use on boards work in slides. See Decks & presentations.
• Knowledge graph — A force-directed map of your vault. Every wikilink and tag becomes a node. Watch your thinking take shape as you write. See Knowledge graph.
• Tasks — Tasks live inside notes as task lines, and roll up into a single hub with list, board, timeline, and matrix views. See Tasks.
• Calendar — Month, week, day, and agenda views. Scheduled tasks and events show up here; you can drag to reschedule. See Calendar.

The sidebar is the hub. Click a surface to switch contexts. Your vault stays open underneath, so jumping from a note to a board to a graph view never loses your place.

Your first note

Let’s write something.

1. Open the Notes surface from the sidebar.
2. Click New note (or use the keyboard shortcut).
3. Type a title and start writing in Markdown.

Markdown is the simple, universal way to write with formatting. You probably know the basics:

# A big heading

## A smaller heading

- A bullet point
- Another bullet point

1. A numbered step
2. Another step
   **bold** and _italic_ and `inline code`

Two things are worth learning right away because they’re how Zettly stays connected:

Wikilinks connect notes to each other. Wrap a note’s title in double square brackets and it becomes a clickable link. If the linked note doesn’t exist yet, Zettly creates a stub for you to fill in later. The graph in Knowledge graph is built from these links.

I keep coming back to the idea in [[On the shoreline of complexity]].
Related: [[Notes on slowing down]] and [[Why local-first matters]].

Tags start with a # and live inline with your prose. They’re how you mark topics, projects, or status — anything you’d want to filter or group by. See Notes & editing for the full set of conventions.

#design #draft #to-review

That’s enough to be dangerous. Save the note and it appears in your vault, ready to be linked, dropped on a board, scheduled as a task, or just left to grow.

Local-first, in real life

A few things to know about how local-first feels in practice:

• Search is local and instant. No network round-trip. Try the global search shortcut and start typing — it searches your entire vault in milliseconds.
• Edits save to disk continuously. You don’t have to remember to save. The app writes through to the file as you type, and your other tools (editors, version control, sync clients) see the changes immediately.
• Multiple windows work. Open the same vault in two windows and edits in one show up in the other. It’s not collaboration in the Google Docs sense, but it’s nice when you want a notes window and a board window side by side.
• Mobile and desktop share the same vault format. The mobile app reads and writes the same files, so your phone and your laptop see the same vault.

A note on alpha status

Zettly is currently in alpha. That means the core experience works — you can write, link, draw, build boards, and use the AI assistant — but you’ll find rough edges. Some features are partially implemented. Some widgets on boards are still in progress. The AI assistant may occasionally get confused by large vaults. The plugin marketplace is small.

This is normal for alpha software, and it’s why your feedback matters. If something feels off, file a bug or send feedback. The point of the alpha is to find the things that need attention before the app is ready for a wider audience.

That said: the vault format is stable. Your data is yours, in a form that will outlast any version of the app. Don’t let the alpha disclaimer scare you off from putting real work into your vault.

Where to go next

You have a vault and a first note. Here’s where to go from here:

• Notes & editing — the full tour of the hybrid editor, wikilinks, tags, templates, and the backlinks panel.
• Boards — drop your first note on an infinite canvas and start wiring things together.
• AI assistant — meet the vault-aware assistant that can answer questions about your notes, propose edits, and build decks.
• Plugins — install Pomodoro, Local AI Models, or File Manager from the marketplace. Enable Suggest note improvements in Flows when you want AI suggestions.

Take your time. The vault is patient.