Notebooks and files

A notebook is an ordinary folder of Markdown files. Cairn reads and writes those files directly, and keeps its own settings in a .cairn folder inside the notebook folder.

The file tree

The file tree has expand/collapse, new note, new folder, inline rename (double-click or F2), delete (Delete key or context menu) and drag-and-drop moves. On the desktop, a deleted file goes to the system trash; on Android, it goes to a .trash folder in the notebook folder. On Windows, what the Recycle Bin cannot take, such as a file on a network share or a USB stick, or one larger than the Recycle Bin takes, goes to the notebook's .trash folder instead. File Explorer shows that folder, but the file tree does not (see Windows). Large folders stay fast because Cairn draws only the visible rows. The tree also works from the keyboard: the arrow keys move through it, Enter opens a note or an image, and Shift+F10 or the Menu key opens a row's menu.

On the desktop, changes made outside Cairn (another editor, git pull, a file manager) show up in the tree and in open notes within about a second. On Android, Cairn looks for them when you switch back to it and every 20 seconds while it is on screen. If a note, or a folder it is in, is renamed outside Cairn, the note stays open in its tab.

File names

Cairn refuses to create, rename or move an entry to a name that differs only in case from another one in the same folder, because macOS, Windows and Android shared storage would treat the two as one file. Changing only the case of an entry's own name works. Cairn also refuses, on every system, the names that Windows keeps for devices, such as CON, NUL, COM1 or LPT1, with any extension.

If one folder holds two file names that differ only in their Unicode form (for example café.md saved on Linux and on a Mac), Cairn shows the second as café (Unicode twin).md. It is the real file under another name: it opens, saves and syncs like any note, and renaming it in Cairn renames the file on disk.

Cairn does not show or sync files and folders whose names contain a backslash (possible on Linux and Android). To use them in Cairn, rename them in another app. With sync on, Settings, then Sync, lists them under "Files not synced" with the reason "The name contains a backslash. Rename it to sync it." If a synced note gets such a name outside Cairn, it counts as deleted, so the other devices move it to their trash.

Images

Images (PNG, JPEG, GIF, WebP, AVIF, SVG, BMP and ICO) open in a tab inside Cairn, on the desktop and on Android: from the file tree, the quick switcher (once you type), search (images whose name or folder matches are listed under the notes), a link, or a click on an image embedded in a note in the reading view. In Live Preview a plain click puts the cursor on the embed to edit it, and Ctrl+click or a middle click opens the image; on a phone, tap the image in the reading view.

The tab shrinks an image that is larger than the tab to fit it; Actual size, or a click on the image, shows it at full size, and the arrow keys scroll it. An SVG is shown only as an image, so scripts in it never run. The tab loads the image again when it changes on disk, follows it when it is renamed or moved, and closes when it is deleted, and the right sidebar lists the notes that link to it. Image tabs are not reopened when Cairn starts again.

Other files

On the desktop, a file that is neither a note nor one of the image types above, such as a PDF or a TIFF or HEIC photo, opens in the system's default app from a link, from the card of an embedded file, or from the file tree (click it, or choose Open in default app in its menu). An image of the types above opens there with Open in default app, in its tab or in its menu in the file tree.

Cairn does this only for documents, images, audio, video, archives and a few text formats (txt, log, csv, tsv, rtf, svg, json, yaml, yml, ics, vcf). It refuses any other type (programs, scripts, web pages, XML, macro-enabled Office files) and text files marked as executable, and suggests Reveal in file manager instead. On Android, Cairn cannot open files in other apps yet, images included.

Settings and hidden folders

Settings live in .cairn/settings.json inside the notebook folder, CSS snippets in .cairn/snippets/, and a font file in .cairn/fonts/. Cairn sync does not copy .cairn/, so another device uses its own settings: to use the font file there, pick it on that device under Settings, then Appearance, then Font file. Cairn refuses a settings file, snippet or plugin larger than 16 MB.

The tree, search and the graph ignore folders whose names start with a dot. Cairn also does not open or display files inside them, so an image kept in a dot-folder does not show in a note or in an image tab.

Symlinks and hard links

Cairn follows the symlinks in a notebook. Linked notes and folders show up and you can edit them, and saving a linked note keeps the link. Hard links are kept too, except on Windows, where saving a note that has hard links replaces it with a new file, so its other names keep the old text. A folder link that loops back (loop -> .) is skipped.

Under .cairn/, Cairn reads through links but writes only inside the notebook folder: when it saves a settings, snippet or font file that links out of that folder, it replaces the link with a plain file. If a folder on the way (.cairn itself, .cairn/snippets for a snippet or .cairn/fonts for a font file) links out of the notebook folder, Cairn writes nothing there and shows an error such as "Could not save settings: The ".cairn" folder leads outside the notebook."

Files under two names

A file you can reach under two names, through a folder link (a link to a folder of the notebook, or two links to one folder) or a link to a note, shows under both names but syncs under one: the name it already syncs under, or for a new file the name with no link on the way (between two links, the one in the fewest folders, then the first by character code). Your other devices get one copy. Hard links sync as separate notes.

Version 1.1.0 and older synced both names, so your other devices may still have a second copy under the link's name. Cairn no longer updates that copy or sends anything for it, with two exceptions: deleting the note on the device that has the link deletes the copy too (unless another device changed the copy meanwhile), and if another device deletes the note's own copy but keeps the second one, the second copy syncs in its place.

Deleting either copy on another device is safe once every device that has the link runs version 1.2.0 or later: version 1.1.0 or older moves the real note to the trash then (for a link to a note, when the note's own copy is deleted), and its next sync deletes the other copy on every device. If another device edits or renames the second copy, the device with the link lists it in Settings, then Sync, under "Files not synced": copy what you need into the note, then delete the copy on a device where it is a separate file. See also the known limits.