Windows, vaults and files

A directory is a vault, a file is a document. Open a folder and you get the three-column shell. Open a single .md file and you get an editor over that one file, with no sidebar and no list.

Keys	What opens
⌘⇧O	A folder, as a vault, in the window you're in
⌘O	A file, in a window of its own
⌘⇧N	A new empty window

That difference is on purpose. A vault is a place you work and you switch places, so it replaces what the window was showing. A document is something you glanced at, so it never displaces what you already had open.

Finder's Open With, the menu bar, the halcyon command and these shortcuts all follow the same rule, so they can't disagree about what you meant.

Reading markdown from anywhere

Opening a file needs no vault, no import, and no copy. Point Halcyon at a README in a repository you just cloned and read it rendered, then close the window. Nothing was added to anything.

This is what the Files section in the sidebar is for: an Open file… button and the single files you opened recently, listed separately from the vault's notes because they aren't in it.

Important

A README from a repository you didn't write is untrusted input, and the preview treats it that way: raw HTML is dropped and link schemes are checked. See Markdown Halcyon renders.

Documents you opened yourself are read-write. If the file is read-only on disk, Halcyon says so rather than pretending the edit landed.

Following a link out of a document

Click a link in a rendered document and the file it names opens in the same window, so reading a repository's docs folder works the way a browser does rather than burying you in windows.

Two things happen differently when the link points somewhere else.

A link that leaves the folder you're reading in asks first. A native dialog shows you the full path of the file that would open, and nothing opens until you say yes. That covers a link written as an absolute path, one that climbs out with ../, and one whose name reads like a neighbour but resolves somewhere else, which is what a symlink beside the file you're reading does. A link to a file that really is beside the one you're reading, or below it, opens on the click.

The reason is that the words in a link and the file it points at are chosen by the same person, and that person often isn't you. [the setup guide](/Users/you/.ssh/notes.md) renders as four words. The dialog is where you find out which file they meant.

A file you arrived at by following a link opens read-only. The header says read-only, until you allow it, and there's an Allow editing button beside it. Click it and a dialog names the file; say yes and you can edit it for as long as that window stays open.

Allowing edits is per file and per window. Navigate on and the next file starts read-only again, and so does the same file tomorrow in a new window. Close the window and the permission goes with it.

Quitting with the window open is the one case where it survives, because the window survives: relaunching brings each window back the way you left it, and a document that was read-only when you quit is read-only again.

A file from the Files list or Open Recent can open read-only too, when Halcyon can't vouch for the entry: one written by a version of the app that didn't record where a path came from, or one whose path now points at a different file than it did. Opening that file from Finder or Open file… once puts the entry back, and it opens writable after that.

A file a link chose doesn't join the Files list or Open Recent either. Those are the way back to files you opened yourself, and anything picked from them opens writable, so what goes into them is the same question as what may be written.

Note

This applies to files a link chose. A file you opened yourself, from Finder, from Open file…, from the halcyon command, from Open Recent, or from the Files list in the sidebar, is writable straight away, and stays writable across a relaunch.

Picking a file from the Files list, the welcome screen or the command palette now gives it a window of its own, the way Open Recent in the File menu always has. It used to replace what a document window was showing.

Several windows at once

Open as many as you like, on different vaults. The arrangement comes back when you relaunch: each window where you left it, showing the note you were reading.

⌘⇧W closes a window. ⌘W closes the note, leaving the window on the vault, and in a document window there's no note to close so it closes the window.

Note

Closing the last window doesn't quit Halcyon. The menu bar stays, the way it does for any other macOS app, and New Window, Open Vault and Open File all still work from there. That's the way back in.

Two windows on the same vault

Allowed, and it works. Both windows see the same files and the same index, and an edit in one shows up in the other the way any external edit does.

If a vault is synced, only one of those windows shows the sync status line. The others are ordinary, fully working windows on the same folder.