Open a vault
A vault is a folder. That is the whole definition: Scoria takes a path, scans the folder below it, and opens. There is no vault file to create, no registration step and no vault picker — the path is the argument.
scoria ~/notesIf the folder has an .obsidian directory, Scoria reads your settings out of it. If it does
not, Scoria uses Obsidian's defaults and still opens the folder fine. Either way, opening
a vault writes nothing.
What happens on open
- The configuration is read first.
appearance.jsonandhotkeys.jsonare read before the window is created, so the first frame already has the right colors and the right key bindings rather than flashing a default theme at you. - The folder is scanned on a background thread: every file below the root, skipping dot-folders. Each file is classified by extension into a kind — Markdown note, image, audio, video, PDF, Canvas, Base, or unknown.
- Every note is read and indexed. The Markdown is parsed once, and from that one parse come the note's links, embeds, tags, headings, sections, list items, blocks and frontmatter. Then every link in the vault is resolved to a file, which is what makes backlinks, the graph and unresolved-link detection possible.
- The window opens on the three-pane shell, with the Files tree on the left.
A 20,000-file vault indexes cold in under two seconds on the reference machine — that is one of the project's gates, not an aspiration. See performance.
What gets read from .obsidian
Every file is optional, and so is every key in it. A key Scoria does not recognize is kept and carried through rather than dropped.
| File | What Scoria takes from it |
|---|---|
app.json | defaultViewMode, livePreview, strictLineBreaks, newLinkFormat, useMarkdownLinks, newFileLocation, newFileFolderPath, alwaysUpdateLinks, trashOption, promptDelete, showUnsupportedFiles, useTab, tabSize, smartIndentList, attachmentFolderPath, userIgnoreFilters, and the rest of the editor and files settings |
appearance.json | Base theme, accent color, text and interface fonts, font size |
hotkeys.json | Your key bindings, replacing the defaults command by command |
core-plugins.json | Which core plugins are on (both the modern map and the legacy array shape) |
community-plugins.json | The list, and each plugin's manifest — shown in Settings, not run |
graph.json | Graph filters, color groups, display settings and forces |
switcher.json | Quick switcher options |
command-palette.json | Pinned commands |
workspace.json | Read, but not applied: Scoria opens its own default layout, and never writes this file, so your Obsidian layout is untouched |
What Scoria writes
While you are only reading, nothing at all. When you edit:
- The note you edited, and only that one. Autosave fires two seconds after your last
keystroke, on
Ctrl + S, when you open another note, when you switch to reading view, and when the window closes. - Notes whose links need rewriting, when you rename or move a file and
alwaysUpdateLinksis on. See managing notes. - Files created or deleted by you, through the Files menu or the commands.
Nothing else. In particular Scoria does not write .obsidian — Settings is read-only at
present, deliberately, because Obsidian rewrites a whole settings file on every change and
that is a round-trip hazard worth getting right rather than quickly. It does not write
workspace.json, so your Obsidian layout is never disturbed. It writes no cache, index or
sidecar file of its own, because it has none.
On save, a file's byte-order mark and its line endings are restored as they were found. A note that was CRLF with a BOM is written back CRLF with a BOM.
Files changed underneath you
Scoria watches the vault folder. A burst of writes — a git checkout, a sync client landing a batch — is collected for 300 ms and applied as one update:
- Added, modified, removed and moved files re-index in place.
- When files appear or vanish, every link in the vault is re-resolved, because a link elsewhere may now resolve or stop resolving.
- The side panes, the search results and the graph refresh.
- An open note reloads, keeping its scroll position.
If you have unsaved edits in a note that changed on disk, your edits are left alone rather than being overwritten by the file. And a reload is skipped entirely when the file on disk is what Scoria itself last wrote.
Several vaults
One Scoria process opens one vault. To work in two, run it twice. app:open-vault and
app:open-another-vault exist as command ids — your hotkeys.json bindings for them are
honored as bindings — but switching vaults from inside the window is not implemented; the
command is not offered in the palette.
Next
- Coming from Obsidian — if the vault is one you use daily.
- The window — what you are looking at.