FAQ

FAQ

Is this an Obsidian alternative?

For a lot of workflows, yes. Soffit reads and writes plain markdown in folders you already have, no vault structure required, no plugin manager, no syncing service of its own. Tiled panes, freeform canvases, and an embedded terminal cover what most Obsidian power users actually do.

For graph view, spaced-repetition flashcards, or Dataview-style queries, no. Soffit is intentionally narrower. If you live in those features, you'll miss them.

Where do my files live?

Wherever you put them. Soffit doesn't move, copy, or convert anything. Your workspace folder is the folder you pick on first launch. Files inside it are read with try String(contentsOf:) and written with try value.write(to:atomically:encoding:). That's it. Use git on the folder, dump it in iCloud Drive, mirror it to Dropbox — Soffit doesn't care.

The only Soffit-specific state on disk:

• ~/Library/Application Support/Soffit/layout.json — pane tree + canvas positions
• macOS Keychain — com.soffit.app (legacy, only relevant if you used chat in v0.2)
• UserDefaults com.soffit.app — recent files, sidebar width

See Persistence for the full inventory.

Why no plugin system?

Two reasons.

First, plugins make markdown apps slow. Obsidian's own startup time is the running joke; that's plugin overhead. Soffit launches in under a second.

Second, the PanelProvider protocol is the plugin system. Add a new URI scheme, conform to a 3-method protocol, register it in AppServices.init. Anyone forking Soffit gets the same plugin model the built-in providers use. There's just no runtime plugin loader because nobody asked for one yet.

Can I use my Obsidian vault as the workspace?

Yes. Just point Soffit at the vault folder. Wiki-links ([[…]]) won't render specially — they'll show as raw text. Frontmatter (---) renders as raw markdown too, not as a styled YAML block. Embedded media, callouts, and other Obsidian-flavoured extensions render plainly.

The plain-markdown bits — headings, code blocks, tables, tasks, links — all work fine.

How do I change the workspace?

Sidebar header → folder gear icon → pick a new folder. Or ⌘O (Open Workspace…).

Tabs you had open from the previous workspace stay open until you close them. They'll render fine for absolute file paths; mermaid panels referenced relative to the old workspace may not resolve.

Why is the chat panel gone?

Removed in v0.3. The terminal + claude (Claude Code) covers everything chat did, with workspace awareness, tool use, and file editing built in. The chat:// provider is still registered so any chat panels persisted before v0.3 still load, but there's no UI to create new ones.

Does it work on Intel Macs?

Yes, though Apple Silicon is preferred. Soffit targets macOS 14+ and ships a universal binary in the DMG.

The first launch warns about an unidentified developer

Right-click the app → Open → Open in the dialog. Soffit's DMG is ad-hoc signed (so the bits are self-attested) but not Apple-notarized (would require a paid Apple Developer account). The right-click dance is a one-time thing per Mac.

If you're really paranoid, build from source:

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

How do I edit a remote file?

You don't, directly. Soffit is local-first. If you want a remote source-of-truth, mount it as a folder (SMB, sshfs, iCloud Drive, Dropbox), point Soffit at the mount point, and the mount handles syncing.

Can I open multiple windows?

Not yet. v0.3 is single-window, single-workspace. Multi-window is a planned feature; track it in Issues.

What about Vim keybindings?

Not built-in. The markdown source editor is an NSTextView, which means it inherits Cocoa's Emacs-style key bindings (⌃A, ⌃E, ⌃F, ⌃B, ⌃P, ⌃N, etc.) but no Vim modal editing.

If you want full Vim, run vim in the embedded terminal instead — open the file there, it's a real terminal.

How do I export a markdown file as PDF?

Open it in Preview mode. ⌘P invokes the standard macOS print dialog, which has Save as PDF as an export option.

(More: there's no built-in PDF export pipeline that's separate from ⌘P. We didn't think we needed one when the system already has it.)

Why "Soffit"?

A soffit is the underside of an architectural element — the part of a ceiling, eave, or arch that you see from below. The name fits an app that's the substrate behind your panes, not the panes themselves.

It's also short, unique, and not already taken on every package registry.

Something's broken / I have a feature request

Open an Issue. For "how do I" or "what if", Discussions is friendlier.

How do I uninstall?

Drag Soffit.app to the Trash. Then optionally:

rm -rf ~/Library/Application\ Support/Soffit
defaults delete com.soffit.app
security delete-generic-password -s com.soffit.app -a anthropic_api_key 2>/dev/null

That removes layout state, recent files, and any leftover keychain entries.