EtherPK User Docs

Graph Folder Layout

A local graph's folder, a Local Mirror and an EtherPK export are the same thing: one layout, holding a graph as plain files. The layout matters to anyone editing the files by hand, scripting over them, or pointing a coding agent at them. EtherPK writes the same description, with the rules an agent must follow, into the folder's own AGENTS.md (Using AI Agents With Your Notes).

The folders

<graph>/
  journals/   2026-06-02.md                     one file per calendar day
  pages/      Quantum Mechanics.md              a page, named after its title
              [[Physics]] Quantum Mechanics.md  a scoped concept keeps its inner brackets
  assets/     diagram.a1b2c3d4.png              images and files, flat
  etherpk/    settings.json, quick-notes.json,  graph settings, quick notes,
              protection.json, theme-<id>.jsonc the wrapped protection key, website themes
  AGENTS.md                                     the folder described to coding agents
  CLAUDE.md                                     imports AGENTS.md for Claude Code
  • Only journals/ and pages/ are read for documents, and only .md files directly in them. A subfolder inside either is ignored.
  • assets/ is flat. Files are named <name-in-kebab-case>.<8 hex characters>.<ext> when EtherPK stores them, the hex being a fingerprint of the contents, but any file name works when you add one yourself.
  • etherpk/ is app-managed. settings.json holds the graph's settings and favourites; quick-notes.json the quick notes not yet moved into the journal; protection.json the wrapped protection key, which must never be edited, moved or deleted; theme-<id>.jsonc a website theme copied into the graph. A Local Mirror adds graph.json.
  • AGENTS.md and CLAUDE.md are written into a local graph's folder, not into a mirror, and are never imported as pages.
  • Nothing else is read. A stray .md at the root or in assets/ is ignored here, though an import of the folder into another graph would pick it up.

Journal entries

journals/YYYY-MM-DD.md. The date is the entry's whole identity: the file name must be a real calendar day, there is at most one file per day, and the file needs no frontmatter (a title: in one is kept but ignored; aliases: works). Journal entries cannot be renamed.

Pages

pages/<name>.md. A page's identity is the title: in its frontmatter, not the file name. The file name is derived from the title with the characters some filesystems refuse (`/ ? < > \ :

  • | ") replaced by _; when two titles derive the same file name the second gets a (2)suffix. A file with notitle:is named after its file name without.md`.

Names are case-insensitive: two pages whose titles differ only in case are a collision, and one silently shadows the other. Check for an existing page or alias before creating one.

To create a page, write the file with a frontmatter block:

---
title: Quantum Mechanics
aliases:
  - QM
---
- first block

To rename a page from outside EtherPK, change title:; renaming the file alone does nothing. Links to the old name are not rewritten by an external rename, so update them yourself or add the old name to aliases:.

A page whose title contains a wikilink, [[Physics]] Quantum Mechanics, is a scoped concept (Scoped Concepts). It is linked as [[[[Physics]] Quantum Mechanics]] and counts as a reference to Physics by its name alone.

Frontmatter

Only at the very start of the file, opened and closed by a line that is exactly ---. Keys EtherPK reads: title, aliases (a YAML list), and the publishing keys public, publications, publication, slug, date and author. Any other key is kept verbatim and ignored. The full meaning of each is in Titles Aliases And Frontmatter and Publishing Your Notes As A Website.

Document syntax

Everything is GitHub-flavoured markdown; EtherPK adds nothing proprietary and derives structure from the text. Document Syntax lists every construct. The rules that matter most when writing files by hand:

  • Bullets are - (hyphen, space). Nesting is two spaces per level, and a child sits exactly one level under its parent. Lines that continue a bullet are indented to its content column, two characters right of the dash. A blank line indented to that column is a paragraph break inside the bullet; a flush-left blank line ends the group.
  • Wikilinks are [[Name]], with no |label and no #anchor form.
  • Tasks are - [ ] and - [x], with their tags immediately after the checkbox.
  • Fences are three or more backticks, closed by a bare fence of the same length at the same column. Tildes are not fences.
  • Assets are referenced by relative path, ![alt](../assets/name.png) for an image and [label](../assets/name.pdf) for a file, with an optional |300 or |640x480 display-size hint after the alt text.

Protected documents

A page whose entire body is one fenced block tagged etherpk-cipher is a protected document. The block is base64 ciphertext, one envelope per line, and it is authenticated: a single changed byte makes the whole document unreadable, with no recovery. Never edit, reformat, re-wrap, re-indent, trim, sort or re-encode the block, never add text before or after it in the body, and never delete the frontmatter above it. etherpk/protection.json is the wrapped key; leave it alone. See Protected Documents.

Keeping files editable by EtherPK

  • UTF-8, LF line endings, no byte-order mark, and a single newline at the end of every file.
  • Spaces, not tabs, for indentation. A tab reads as one character to the editor and four columns to the importer, so a tab-indented outline is misread as soon as it is touched.
  • Do not run a markdown formatter (Prettier, mdformat, an editor's format-on-save) over the folder. They re-indent nested bullets to four spaces, re-wrap paragraphs and rewrite fences, each of which changes meaning.
  • Do not strip trailing whitespace or blank lines by formatter. A whitespace-only line indented to a bullet's content column is part of that bullet; flattening it splits the block.
  • Keep fences balanced. An unterminated fence turns everything below it into plain text.
  • Never leave two pages with the same title or alias, a page titled with a calendar day, or a journal file not named after a real day.
  • Write each file once, whole, rather than in several passes, and do not hold a file open with unsaved changes in another editor while EtherPK is autosaving it. EtherPK reloads files that change on disk and asks before overwriting an edit of yours (Local Graphs).