How SideNotes Works.

SideNotes is a desktop app built on Electron. Builds for macOS (Apple Silicon and Intel), Windows, and Linux are published on GitHub Releases. macOS gets the most testing; the other platforms come from the same CI pipeline but have less mileage , bug reports welcome.

macOS

1. Download the .dmg for Apple Silicon or Intel from the Download section on the landing page.
2. Open the .dmg and drag SideNotes into /Applications.
3. First launch is unsigned in v0.2, right-click the app and pick Open the first time so Gatekeeper lets it through.

Windows

Run SideNotes-Setup-x.y.z-x64.exe (or the arm64 build on Surface devices). NSIS installs per-user; no admin rights needed.

Linux

Download the .AppImage, chmod +x SideNotes-*.AppImage, and run it. AppImages are self-contained, no install step.

Build from Source

git clone https://github.com/Koushith/side-deck
cd side-deck
npm install
npm run dev

That launches Vite + Electron in development mode. npm run build produces a packaged binary in release/.

SideNotes does not store your notes in a database or in the cloud. Your vault is just a folder on disk full of .md and .canvas files. You own every byte.

First Launch

The onboarding tour opens automatically. Step four asks you to Pick a vault: choose any folder on your computer , empty or full of existing markdown, and SideNotes indexes it.

Switching Vaults

Click the S chip at the top of the sidebar to close the current vault and pick another. You can also run Switch vault from the command palette (⌘K).

What Lives in the Vault Folder

• *.md: your notes. Plain markdown with optional --- frontmatter.
• *.canvas: whiteboard files. JSON, compatible with Obsidian's canvas format.
• assets/: created automatically when you paste or drop an image. Files are stored relative to the vault.
• Daily Notes/: created the first time you press ⌘D. One file per day, named YYYY-MM-DD.md.
• templates/: drop any .md file here and it shows up as a "New from template" option.

The window has three top-level views, switched from the sidebar or with a keyboard shortcut. Each view shares the same vault index, so opening a note from any of them lands you in the editor.

Editor

The default. Block-style writing surface for one note at a time, with a left rail for the file tree and a right rail for backlinks and the outline. Press ⌘1 to return here from anywhere.

Graph

A WebGL force-directed map of every wikilink in your vault. Press ⌘2. Hover any node to highlight its neighbours; click to open. The graph colours notes by their top-level folder so structure is readable at a glance.

Canvas

An infinite whiteboard. Open from New canvas in the command palette, or click any .canvas file in the sidebar. Drag notes onto the canvas to embed them as live cards.

Sidebar

The left rail, top to bottom:

• Vault chip: click to switch vaults.
• Search: opens the command palette.
• Today: jumps to today's daily note, creating it if needed.
• All notes: flat, sortable list of every note.
• Pinned: filters the file tree to your pinned notes.
• Connections: opens the graph view.
• File tree: folders + files. Drag to reorder, right-click for the context menu.
• Tags: every tag in your vault, sorted by count. Click one to filter the tree.

Tabs

Open files appear as tabs at the top of the editor. Drag to reorder. ⌘W closes the active tab.

Focus Mode

Press ⌘. and the sidebar slides away, just the page. Esc brings it back.

The editor is built on TipTap, with a markdown round-trip on every keystroke. What you see is rendered HTML; what is on disk is plain markdown. You never have to leave one for the other.

The Slash Menu

Press / on a new line and a menu opens with every block you can insert: headings, bullet and numbered lists, task lists, quotes, code blocks, tables, images, dividers. Filter by typing, /h2 jumps straight to a heading.

Markdown Shortcuts

Type these at the start of a line and the editor transforms them in place. Nothing to memorize beyond muscle memory you may already have.

• # : Heading 1. ## , ### work too.
• - : Bullet list. 1. : Numbered list.
• > : Quote.
• ```: Code block. Add a language after the backticks for syntax highlighting.
• ---: Horizontal divider.
• [ ] : Task list item.

Inline Formatting

Select text and a bubble menu floats above it. Or use the shortcuts: ⌘B bold, ⌘I italic, ⌘E inline code. Markdown like **bold** and `code` works too.

Drag Handles

Hover the left margin of any block, a handle appears. Drag to reorder, or click for a block menu (delete, duplicate, turn into).

Images

Paste from the clipboard or drop a file into the editor. Images are saved into <vault>/assets/ and referenced relatively, so the vault stays portable.

Code Highlighting

Code blocks render with syntax highlighting via lowlight (a light wrapper around highlight.js). Most common languages are detected automatically; you can also annotate the fence: ```ts.

Tables

Insert from the slash menu. Add columns and rows from the block menu, or use Tab/Shift-Tab to navigate cells.

Linking is the difference between a notes app and a second brain. SideNotes gives you three light syntaxes, pick whichever fits the moment.

Wikilinks: [[

Type [[ anywhere and an autocomplete pops up. Pick an existing note, or type a new name and press ↵ to create it. Aliased links work too: [[Database indexing|the indexing post]] renders as the indexing post but links to Database indexing.

Mentions: @

Type @ for a unified picker:

• Note titles: @Atomic Habits inserts a wikilink.
• Tags, @meeting inserts #meeting.
• Dates, @today, @yesterday, @monday, @2026-05-08 all link to the matching daily note.

Tags: #

Type # followed by letters and an autocomplete shows existing tags. Tags appear in the sidebar's Tags section, sorted by count. Click any tag in the sidebar to filter the file tree to notes that contain it.

Backlinks

The right rail of the editor shows every note that links to the one you have open, with a snippet of the surrounding text. Backlinks update as you type, in either direction.

Connections Panel

Below backlinks, the Connections panel shows the immediate neighbourhood of the current note as a tiny graph, a fast-loading preview of the same data you see in the full graph view.

Canvas is built on React Flow. It is for the parts of thinking that resist a linear page, sequencing, clustering, mind-mapping, mood boards.

Creating a Canvas

Open the command palette (⌘K) and run New canvas. Give it a name and it appears in the sidebar with a grid icon.

Adding Cards

• Drag a note from the sidebar onto the canvas, it embeds as a live card that reflects the note's current contents.
• Double-click empty space for a free-form text card.
• Drop an image onto the canvas to add an image card.

Connecting Cards

Hover a card edge, small handles appear. Drag from one handle to another card to draw an arrow.

File Format

Canvases save as .canvas files in your vault using the same JSON schema Obsidian uses. You can hand-edit them, version-control them, and switch between SideNotes and Obsidian without converting anything.

The graph is a Sigma + Graphology view of every wikilink in your vault. Press ⌘2 to open it.

Reading the Map

• Node colour: derived from the note's top-level folder. Move a note between folders and the colour follows.
• Node size: scaled by the number of links in and out.
• Hover: neighbours stay bright; everything else fades. The note title pins to the cursor.
• Click: opens the note in the editor.
• Drag: repositions the node. Layout is physics-based, so other nodes adjust around it.

Local-Graph Mode

Toggle local mode to focus on the active note plus one or two hops out, useful when the global graph gets noisy.

Press ⌘D any time to open today's daily note (created on the spot if it does not exist). Files live under Daily Notes/YYYY-MM-DD.md.

The Masthead

Daily notes open with a header that shows the date in long form, a mood strip you can click to set the day's tone, a streak chip, and a "Yesterday's loose ends" panel that pulls unchecked task-list items from the previous day's note.

Templates for Daily Notes

Drop a markdown file at templates/daily.md and SideNotes uses it as the body for new daily notes. The template can include {{date}} tokens.

Any markdown file inside a top-level templates/ folder is treated as a template. They show up in the command palette as "New from template: <name>".

Tokens

• {{title}}: the name you typed in the prompt.
• {{date}}: today's date, ISO format.
• {{time}}: current time, 24-hour.

Example

---
title: {{title}}
created: {{date}}
---

# {{title}}

## Notes

## Action items

Press ⌘K from anywhere in the app. The palette is one surface for three jobs:

• Jump to a note: fuzzy match on title. With no query it shows your eight most recently edited notes.
• Search note bodies: type two or more characters and SideNotes searches inside file contents, returning matched snippets.
• Run a command: new note, new canvas, today's daily note, switch vault, open graph view, show keyboard shortcuts, replay the onboarding tour, create from any template.

Use ↑/↓ to move, ↵ to run, Esc to close.

Creating

• ⌘N creates an untitled note in the vault root.
• Right-click a folder for New note / New folder in that location.
• The plus icon next to a folder name in the file tree does the same.

Moving

Drag a note onto a folder to move it. Drop it on the empty space at the bottom of the tree to move it to the vault root. SideNotes updates the underlying file path; wikilinks that resolved to it keep working because they match by basename.

Renaming and Deleting

Right-click any note for Rename, Duplicate, Reveal in Finder, and Delete. Rename changes the file on disk; references that pointed at the old basename keep resolving by title where possible.

Pinning

Right-click a note → Pin. Pinned notes appear above the tree, and clicking the Pinned nav item filters the tree to just those.

Tabs

Click any note to open it in a tab; the previous tab stays open. Drag tabs to reorder. ⌘W closes the current tab. Tabs persist across launches.

Right-click a note (or use the editor's title menu) → Export. Three formats:

• Markdown: copies the raw .md file. Useful for sharing a single note out of context.
• HTML: renders to a self-contained HTML file with embedded styling.
• PDF: uses Electron's print engine, so the PDF matches what you see on screen, including images.

Open the theme picker from the sidebar (the sun icon in the bottom row). Each theme ships in a light and a dark mode.

• Paper: warm cream and terracotta. The default.
• Ink: neutral white and blue. The cleanest, most professional.
• Forest: green and amber. Calm.
• Dusk: desaturated brown and rust.
• Carbon: minimal charcoal with violet accents. Lower contrast for long sessions.
• Rose: light pink with crimson accents.

Themes are CSS-variable driven, so the editor, the graph, and the canvas all change at once.

SideNotes does not run a sync service and never will. Your vault is a folder, so anything that syncs folders works:

• iCloud Drive: point your vault at ~/Library/Mobile Documents/com~apple~CloudDocs/SideNotes.
• Dropbox / Google Drive / OneDrive: anything that mounts as a normal folder is fine.
• Syncthing: peer-to-peer, no third party. Recommended if you care about privacy.
• Git: version control your notes. Add an assets/.gitattributes with * binary if image diffs get noisy.

SideNotes reads and writes plain markdown, no proprietary extensions. A note looks like this:

---
title: Database indexing
created: 2026-05-08
---

# Database indexing

The slow query was a sequential scan on a billion-row table.
[[Postgres performance]] would have caught it in review.

Related: [[Query planning|the planner]], #database, #performance.

- [ ] Add covering index for the hot path
- [x] Backfill metric for sequential scans

• Frontmatter: optional YAML between --- fences. SideNotes reads title as the canonical title; everything else is preserved untouched.
• Wikilinks: [[Target]] or [[Target|Display]]. Resolved by basename, so moving the file does not break the link.
• Tags: #tag in body text (not in headings, code, or URLs).
• Tasks: standard markdown task lists. Unchecked items from yesterday surface in the daily-note masthead.

Canvas files use the JSON schema Obsidian publishes for .canvas. Open them anywhere; they round-trip cleanly.

Open this panel inside the app any time with ⌘/. On Windows and Linux, ⌘ means Ctrl.

Navigation

Files

In the Editor

Markdown Shortcuts (Just Type)

Help

Notes from Another Editor Are Not Showing Up

SideNotes watches the vault folder using the OS file events. If you are syncing through a service that writes files in odd orders (some cloud drives), close and reopen the vault from the sidebar to force a re-index.

The Graph Is Empty

The graph only renders edges for resolved wikilinks. If your notes are connected by markdown links ([text](url)) instead of [[wikilinks]], the graph stays sparse. Convert with a find-and-replace, or just start using [[ from now on.

Image Paste Creates a Broken Link

Check that <vault>/assets/ exists and is writable. If you renamed the vault folder while SideNotes was open, restart the app.

The App Feels Slow on a Huge Vault

v0.2 indexes the whole vault on launch. 10k+ notes is fine on modern hardware, but the initial scan can take a few seconds. Subsequent launches are fast, the index is in memory and updated incrementally as files change.

I Want to Start Over

Quit SideNotes. Pick a different folder as your vault on next launch (or the same folder, after moving files out). SideNotes has no global database to reset, there is no state outside the vault.

The repo is at github.com/Koushith/side-deck. Issues, discussions, and PRs are welcome.

• Bug reports: please include the OS, the SideNotes version (sidebar bottom row), and reproduction steps.
• Feature ideas: open a discussion before a PR for anything bigger than a polish fix; the v0.2 scope is intentionally small.
• Themes: themes are pure CSS-variable palettes. Adding one is a single object in src/stores/theme.ts.

SideNotes is MIT-licensed. Use it however you want.