Editing the source, and what the app writes

Every click in the app ends up as a change to a text file you can read. This page covers the Source view, and then goes through what each action in Writing and editing and Blocks writes, so you know what to expect in a diff, in a sync client's history or in another editor.

The Source view

Source, in the top bar, shows the document's raw markdown and frontmatter in an editor with syntax highlighting for both the markdown and the YAML inside block fences. A gutter shows diagnostics: YAML errors, invalid frontmatter and validation problems in a block's props, each on the line concerned.

Save with Cmd+S or Ctrl+S; there's no Save button in this view. A status line above the editor says "Saved" or "Unsaved changes. Press ⌘S or Ctrl+S to save." If the file changes on disk while you're editing it, a banner says so, with a button to discard your edits and reload. The same banner appears if a save is rejected for that reason.

Cmd+F in this view searches the text in the editor and selects each match.

New document saves the name you typed with .md on the end, holding one line: the name as a # heading.
A folder's page is the INDEX.md inside it (index.md does the same job), and the vault's own page, the one its name opens, is the INDEX.md at its root. A folder without one opens as a blank page and nothing is written until the first save, so looking into folders never creates files. Vaults has the rest.
Duplicate writes name (Copy).md beside the document, or (Copy 2) and on when that's taken, and adds the same to its title (the frontmatter title, or else the first # heading). The number sits inside the brackets because name 2.md is how iCloud Drive names a conflicted copy.
Delete removes the file from disk. There's no trash. Delete page on a folder, or on the vault's name, removes its INDEX.md and leaves the folder.
A name that can't be used, one that's taken or starts with a dot, is refused with the reason under the name box.

What the top bar writes

Clicking Infinite or Paginated writes layout: into the document's frontmatter, adding a frontmatter block if there isn't one. That's why the choice sticks for everyone sharing the vault. The switch is disabled while Source has unsaved edits, or while the frontmatter doesn't parse; hover it to see why. vault.json and frontmatter covers the key and the vault-wide default.

The theme selector writes nothing. It's a preview for the session.

An old link with ?mode=read or ?mode=print opens the Document view.

What editing text writes

Saving an element replaces that element's lines and nothing else. A new paragraph gets a blank line either side where it would otherwise touch its neighbours, and a paragraph left holding only markup (a ## with nothing after it) isn't written.

A table is written back tidy whenever you change it: every column padded to its widest cell, alignment in the row under the headings, and a | typed in a cell escaped as \|. A table you only look at isn't rewritten. A table saved from Edit as markdown is tidied the same way.

Deleting a selection that spans elements is written as one change: the first element's remaining text joined to the last's, with the first element deciding what the result is (a heading joined to a paragraph is still a heading).

What a block's form writes

Adding a block writes its fence with its schema's default values. Saving a form rewrites only the YAML lines that changed, and keeps comments, key order and formatting everywhere else in the fence. A field left at its default stays out of the YAML, so a fence only records what someone chose.

A block gets a form when it's a core block or an approved package block. Everything else opens as its markdown, the whole fence, in the same inline editor text uses: ts-block code, a block with a YAML error, an unknown block, a package block that isn't approved, and a plain code fence. A block with a form can be opened as markdown too, with Edit as markdown in the panel or Markdown on the block's toolbar. If a block's schema can't be turned into a form, the panel says so and points at editing the markdown.

A markdown field inside a block (a columns item, a callout's body, a card) is edited on the block, and the save goes into that prop of the fence. A callout opens as the markdown callout it stands for, so its first line, > [!warning] Title, is where the type and title change.

What the width control writes

The width is an attribute at the end of the fence's first line: ```card becomes ```card {width="wide"}, or narrow or full. It's written straight away, whether or not the form has unsaved changes, and it changes only that line.

A table, an image or a paragraph takes the same attribute in a comment on the line above it, , which doesn't show on the page. Core blocks says what each width means on screen and on paper.

What pasting a picture writes

The file is saved in the vault's assets/ folder. A screenshot is named after when it was pasted (pasted-2026-09-17-101500.png). A copied file keeps its name with anything awkward replaced by a hyphen, and a name that's taken gets a number, unless the file already there is the very same image, in which case it's reused.

The document gets an image block pointing at it. Move into the text replaces that block with an embed at the caret, ![[assets/name.png]], keeping the block's text for screen readers if it had any. The image editor's controls are the block's props: caption, alt, align, height and fit; see image. Make it a header sets the block to full width and fit: cover in one step.

Deleting an image block leaves the file in assets/. Copying one puts the picture and the block's markdown on the clipboard, and pasting that markdown back into a document makes the same block again, pointing at the file that's already there.

What Vault settings writes

The settings screen edits .vault/vault.json, and it's careful with that file because it's yours. It writes only the key you changed and leaves the rest as you wrote it, in the same order and with the same indentation. Putting a setting back to its default takes the key out of the file, so the file only ever says what you chose. Opening the screen writes nothing.

If the file can't be read (a stray comma, a page size that doesn't exist) the screen shows what's wrong in place of the settings and changes nothing until it's fixed, because saving would write over what's there. Block aliases, shared placeholder values and block settings aren't on the screen; edit them in the file. The foot of the screen says where it is, and Show in Finder (Show in File Explorer on Windows) takes you to it.

Saves check the file first

Every save checks that the lines it's about to replace still read as they did when you opened them. If they changed on disk in the meantime, because another program or a sync client wrote the file, the save is refused with Discard mine and reload. There's no merge.

If something else moves those lines while you're editing (switching the layout adds a layout: line above the document, say), the editor follows them, as long as the text you started with still appears exactly once in the document. Otherwise it stays on screen so your edit isn't lost, and saving reports the conflict. An add made with the picker is refused the same way if the document changed around that spot after the picker opened.

Undo history is cleared by a change from outside the app, since stepping back past it would undo someone else's work.

Live reload

The app watches the vault's folder. Editing the open document in another program reloads it. Editing a block or theme file, or vault.json, refreshes the catalogue of installed blocks and themes and recompiles what needs it. This is the same mechanism that makes a synced folder update as changes arrive from someone else's computer.

Approvals made with plicine trust while the app is open show up the next time a document loads, because approvals live in the app data folder, which isn't watched.

Running it in a browser

plicine open <vault> serves the same app to a browser on your own computer (CLI reference). Two things differ from the desktop app: Export PDF opens the PDF in a new tab instead of saving it to Downloads, and there's no Show in Finder. The server only answers on 127.0.0.1, so it can't be reached from another device.