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. Soffit's DMG is ad-hoc signed but not Apple-notarized, so macOS asks once. After that, double-click works.

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. No .soffit/ dotfile gets created in your workspace.
  2. The folder opens as a card grid.
  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.

Switch a folder to canvas

In the folder grid header, toggle Grid → Canvas. Drag files anywhere. Add sticky notes. Pinch to zoom. Layout persists per folder.

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 with {{date}} / {{long_date}} substituted.

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. Six colours, three brush widths, undo + clear.

Embedded terminal

Sidebar → New Terminal drops you in a real shell rooted in your workspace. Run claude, git, vim, anything.

Quit and reopen

Everything comes back. Pane tree, tabs, modes, canvas item positions, sketch strokes. Terminals respawn fresh.

Next

Soffit · MIT-licensed · macOS 14+

Soffit

Start here

Reference

Repo · Releases · Issues

Clone this wiki locally