Graph Folder Layout
A graph folder holds one graph as plain files in four fixed folders. Journal entries go in journals/, one Markdown file per day, and pages go in pages/. assets/ has the images and other files that documents link to, and etherpk/ has the files EtherPK manages. A local graph folder also contains AGENTS.md and CLAUDE.md, with instructions for coding agents.
journals/ 2026-06-02.md
pages/ Garden.md
[[Garden]] Notes.md
assets/ seed-tray.a1b2c3d4.png
etherpk/ settings.json, quick-notes.json,
bookmarks.json, dictionary.txt,
protection.json,
theme-<id>.jsonc
AGENTS.md
CLAUDE.md
You find this layout in three places. In a local graph folder the files are your notes, and EtherPK reads and writes them without keeping another copy. The other two are copies of a graph stored on the Sync Server (a synced graph). A Local Mirror is a folder that EtherPK writes from the synced graph and never reads back, and an export zip holds the same folder in a single file. EtherPK imports all three the same way.
EtherPK identifies a journal entry by the day in its file name, and a page by the title in its frontmatter. If you edit the files by hand, with a script or through a coding agent, follow the naming and whitespace rules below. Otherwise EtherPK will read a file differently afterwards.
Folders
EtherPK treats only the .md files directly inside journals/ and pages/ as documents and ignores any subfolder in either one.
EtherPK rewrites its own section of AGENTS.md and CLAUDE.md each time it opens the graph, so keep your own instructions above or below that section.
The etherpk folder
| File | Holds |
|---|---|
settings.json |
Graph settings and favourites |
quick-notes.json |
Quick notes not yet moved into a journal entry |
bookmarks.json |
Your bookmarks |
dictionary.txt |
Words that spell check accepts in this graph, one per line |
protection.json |
The protection key record, once protection is set up |
theme-<id>.jsonc |
A website theme copied into the graph |
Do not create, rename or delete anything in etherpk/. The only edit to make there by hand is adding a word to dictionary.txt: EtherPK merges the words on disk before each write, so it keeps yours. It writes the settings, quick notes, bookmarks and theme files whole from its own copy, so if you edit one of them while the graph is open, the next write loses your edit.
Protected documents are encrypted, and EtherPK needs the protection key to read them. protection.json holds that key, wrapped with your passphrase and never in plain form. If you edit, move or delete the file, every protected document in the graph becomes unreadable, and without a copy of the file there is no way to recover them. See Protected Documents for more information.
Journal files
A journal file takes its name from a real calendar day, as journals/YYYY-MM-DD.md, and there is one file per day. You cannot rename a journal entry.
Page files
A page takes its name from the title: in its frontmatter, not from its file name. If title: is missing or empty, the page falls back to the file name without .md. Page names are not case-sensitive, so if two page files have titles that differ only in case, one hides the other.
When you create or rename a page in EtherPK, the file name comes from the title, with _ in place of each / ? < > \ : * | ". If two titles give the same file name, the second file gets a number, as in Garden_Kitchen (2).md, but its title stays as written.
To add a page by hand, create pages/<name>.md with a title: and any aliases: in its frontmatter:
---
title: Garden
aliases:
Vegetable Patch
---
water the beans
To rename a page outside EtherPK, change its title:. If the page has a title:, renaming the file alone does not rename it. EtherPK does not rewrite links to the old name, so update those links or add the old name under aliases:. See Titles Aliases And Frontmatter for more information.
Asset files
A document links to an asset by its path relative to the document, ../assets/<file name>. If you rename or delete an asset, every link to it breaks until you update the links. When you add a file to a local graph through EtherPK, a fingerprint of its contents goes into its name, as in seed-tray.a1b2c3d4.png. A file you copy into assets/ by hand can have any name.
Copies of a synced graph
If you edit a file in a Local Mirror, EtherPK overwrites the edit the next time it updates the whole folder. For example, it does that when you open the graph, select Mirror now, or rename or remove a page. To work on the files, import the folder, or a zip made with Export as zip…, as a new graph on any device. See Keeping A Local Copy Of A Synced Graph for more information.
Rules for editing files
- Save files as UTF-8 with LF line endings, no byte-order mark and one newline at the end.
- Indent with two spaces per level, never tabs. The editor counts a tab as one character and the importer as four columns, so a tab-indented outline is misread.
- Do not run a Markdown formatter such as Prettier. It re-indents nested bullets to four spaces, re-wraps paragraphs and rewrites fences, and together those change the outline.
- Keep lines that hold only whitespace. A line of spaces indented to a bullet's text is part of that bullet, so removing it splits the block.
- Close each fence with one of the same length at the same column. If you leave a fence open, the editor shows every line below it as plain text.
- Write each file whole in one go, and do not leave a file open with unsaved changes in another editor. EtherPK saves its own edits automatically, and it reloads any file that changes on disk while the graph is open. If the other editor later saves its older copy, EtherPK loads that copy and you lose the edits you made in EtherPK.
- Never change the block in a protected document. It is authenticated, so one changed character makes the whole document unreadable for good.