Quickstart

Quickstart

The 60-second tour.

Install

Pre-built

1. Grab Soffit-<version>.dmg from Releases.
2. Open the DMG → drag Soffit to Applications.
3. First launch: right-click → Open → Open in the Gatekeeper dialog. The DMG is ad-hoc signed, not Apple-notarized, so macOS asks once. After that, double-click works normally.

From source

git clone https://github.com/lukataylo/soffit.git
cd soffit
./scripts/vendor-mermaid.sh                                            # one-time
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift build -c release
./scripts/build-app.sh release
open build/Soffit.app

Requires macOS 14+ and Xcode 15+ (full Xcode, not just Command Line Tools — XCTest doesn't ship with CLT).

First launch

1. Soffit asks you to pick a workspace folder. Pick anything — your Notes folder, a project repo, your Obsidian vault, a fresh empty folder. No .soffit/ dotfile gets created. Soffit just reads and writes the markdown files you already have.
2. The folder opens as a card grid: one card per file, each showing a live excerpt.
3. The sidebar shows folders, recent files, and a New Terminal shortcut.

Open files

• Single click a card → opens in a tab in the focused pane. Preview mode by default (rendered).
• Double click → opens in Split mode (source + rendered side-by-side).
• Or drag a file from the sidebar onto a pane.

Tile your space

Three ways to split:

• Drag a tab over another pane. A 4-way compass appears. Drop on an arrow to split that pane on that side.
• Use the menu — ⌘\ splits right, ⌘⇧\ splits down.
• Pane menu — click ⋮ in the tab strip → Split Right / Split Down.

To merge: drag a tab onto another pane's tab strip. It becomes a tab there.

To close a pane: pane menu → Close Pane. Or close the last tab.

Switch a folder to canvas

In the folder grid header, toggle Grid → Canvas. Now the folder is a freeform space. Drag files anywhere. Add sticky notes. Pinch to zoom. Two-finger drag to pan.

Layout persists per folder. See Canvas mode for details.

Edit markdown

Three modes via the toolbar pill above the pane:

Mode	What it shows
Preview	Real GFM render. Tables, code, lists, links, all formatted.
Source	Raw markdown, monospace, paragraph-scoped highlighting.
Split	Source on the left, rendered on the right.

Autosave on a 500ms debounce. Tab close flushes any pending edit. See Markdown editing for the full toolbar reference.

Run a terminal

Sidebar → New Terminal spawns a real shell rooted in your workspace. Everything works: claude, git, vim, npm run dev, tail -f. The terminal is just another pane — drag it, split it, close it like any other.

Quit and reopen

Everything comes back. Pane tree, tabs, modes, canvas item positions. Terminals respawn fresh — they don't survive a relaunch.

Layout state lives at ~/Library/Application Support/Soffit/layout.json. See Persistence.