Skip to content

Quickstart

Jump to bottom
lukataylor-pixel edited this page May 3, 2026 · 3 revisions

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.

From source

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

Requires macOS 14+ and full Xcode (Command Line Tools doesn't ship XCTest).

First launch

  1. Soffit asks you to pick a workspace folder. Pick anything — your Notes folder, a project repo, your Obsidian vault.
  2. The folder opens as a card grid. Each card shows a live excerpt.
  3. Soffit indexes every markdown file in the background. Search, wiki-links, tags, and the outline are ready in seconds.

Open files

  • Single click a card → opens in Preview (rendered).
  • Double click → opens in Split (source + rendered).
  • Or ⌘P → type to fuzzy-find any file in the workspace.

Navigate

  • ⌘P — quick palette (file/heading jump)
  • ⌘⇧F — full-text search across the workspace
  • ⌘⌥F — find / replace across the workspace
  • [[Wiki-links]] — type them, click them, navigate them
  • Backlinks side panel — see what links here
  • Outline side panel — heading TOC of the current file

Tile your space

  • Drag any tab over another pane → 4-way compass picks the split side.
  • ⌘\ splits right, ⌘⇧\ splits down.
  • Drag tab onto a pane's tab strip to merge.
  • Drag the right edge of the sidebar to resize it.

Multiple windows

⌘N opens a new window of the same workspace. Each window has its own pane tree, so you can have one window with your PRD + diagram and another with a quick-reference doc — they don't fight each other.

The first window of the session is the persistent one — its layout is what gets saved to disk and restored on launch. New windows are ephemeral; closing one just goes away.

Edit markdown

Four modes (toolbar pill above the pane):

Mode What it shows
Preview Real GFM render (tables, code, lists, links, wiki-links, frontmatter card)
Source Raw markdown, monospace, paragraph-scoped highlighting
Split Source on the left, rendered on the right
Math KaTeX-rendered preview for $…$ and $$…$$

Daily notes

⌘⇧D — opens (or creates) daily/YYYY-MM-DD.md. Optionally seeded from .soffit/templates/daily.md.

Snippets

Type ,date<space> → today's date. Define your own in ~/.soffit/snippets.json.

Sketch

File → New Sketch or + menu in any tab strip. Drag to draw.

Embedded terminal

Sidebar → New Terminal drops you in a real shell rooted in your workspace.

Quit and reopen

Everything in the primary window comes back — pane tree, tabs, modes, sketch strokes. Terminals respawn fresh.

Next

Soffit · MIT-licensed · macOS 14+

Soffit

Start here

Reference

Repo · Releases · Issues

Clone this wiki locally