EtherPK User Docs

Graph Settings

Settings is a single dialog for the open graph, titled Settings and Extensions. A switch at the top moves between its three areas: Settings, Extensions and Install. The Settings area has tabs for General, Spelling, Protected Documents, Mirror and Export (synced graphs only), Agents, Publish and Maintenance, and in a narrow window the tabs turn into a drop-down list.

The graph keeps its own settings, so on a synced graph every member has the same ones, encrypted like your notes. A local graph keeps them in etherpk/settings.json in its folder. Device settings stay in this browser, and the app never syncs or exports them.

The General tab holds graph settings, plus one device setting, Folder path on this device, when the graph is a local graph in a folder on disk. Changes there take effect when you press Save, and Cancel closes the dialog without saving them. Every other tab and area applies a change as you make it, or with a button of its own, so the footer there has Done instead.

Opening Settings

In the desktop layout, open Settings with the Graph name and settings button, a cog at the right of the toolbar.

The Graph name and settings button, outlined, a cog among the buttons at the right of the toolbar

In the phone layout, use the Settings row at the foot of the Graph Sidebar instead.

On the Graphs page, the Graph settings cog beside a graph opens Settings without opening the graph. Settings then shows only the parts that work without an open graph: General (without Journal Template and Folder path on this device), Maintenance and Install.

General

Field Description
Graph name Rename the graph. On a synced graph, every member sees the new name. On a local graph, the folder on disk keeps its old name. See Managing Your Graphs.
Default maximum image display size on upload Add a size hint to each image you upload: a width (800) or a width and height (800x600). A blank field means 800, so enter 0 for the natural size. See Images And Files.
Default code language Add this language word to each new code block. See Code Maths And Diagrams.
Recent documents shown in the sidebar Set how many documents the Recents list in The Graph Sidebar shows, from 1 to 50 (10 by default).
Journal Template Choose the Template that today and later days open with, or None. If that page stops being a Template, you see "Template not found." and new days open empty. See Templates.
Toolbar colour Colour the toolbar (the tab strip in the phone layout) with one of eight colours or any colour from the picker. The colour stays the same in light and dark themes. Use theme colour removes it.
Folder path on this device Record where a local graph's folder is on this device. The MCP command on the Agents tab uses the path, and the first time you use Copy full file path to clipboard in a document tab's menu or Copy agent instruction on a task or a lane, EtherPK asks for the path. See Local Graphs.

Spelling

Check spelling as I type turns Spell Check on or off for every graph on this device, but you pick the Languages on this device for each graph separately. Every member shares the Graph dictionary.

Protected Documents

Until the graph has a protection passphrase, the tab offers Set up protection…. After that, it shows two lock timings, which apply to every graph on this device and are saved as soon as you change them. See Protected Documents for more information.

Mirror and Export

The Local Mirror is a one-way, plain Markdown copy of the graph in a folder on this device, kept up to date as you edit while the graph is open. Export as zip… makes a one-off zip of the Markdown files, attachments and settings, which you can import as a new graph. See Keeping A Local Copy Of A Synced Graph for more information.

Agents

The tab has a sub-tab for each way of working with an agent. When Agent Chat is switched off, only the first one shows, with no tabs.

  • MCP Server is for an AI agent on your device that should read and change your notes. It gives the commands for connecting one through The Headless Client, written for whichever agent you pick: Claude Code, Codex, Cursor, VS Code or Other.
  • Agent Chat is for asking a language model about your notes from inside EtherPK. It holds your model connections and chat instruction.

The rest of this section is about MCP Server.

On a local graph, the sub-tab points to the AGENTS.md file at the top of the graph folder. Once Folder path on this device is set, it also gives a command that serves the folder to the agent over MCP, with search, backlinks and tasks.

On a synced graph, the sub-tab has three steps: 1. Sign in the agent's device, 2. Tell the agent about this graph and 3. Hand the agent a task. In the first, Create an Agent Setup Code makes a one-time code along with the sign-in command.

On a graph kept in the browser, such as the demo graph, the sub-tab says that an agent cannot reach the graph. It links to the Graphs page, where you can open a local or a synced graph.

Under (Optional) Additional Capabilities, which is step 4 on a synced graph, every kind of graph has Add the EtherPK skill to your agent, which gives the command that installs the skill. An agent only needs the skill to make a new graph folder, check it and publish it. See Using AI Agents With Your Notes for more information.

Publish

The Publish tab has a card for each publication under Publications, a list of the public documents that belong to no publication, and Themes in this graph. See Publish Settings for more information, and Publishing Your Notes As A Website for a first site.

Maintenance

Nothing on the Maintenance tab runs until you press it. Its tools are grouped in three sections: Duplicate names on a synced graph, then Storage and Formatting.

On a synced graph, Storage shows how much space documents and assets take on the server.

If the browser cannot store the search index, the app rebuilds it on every visit, so a large graph opens more slowly.

Rebuild search index reads every document again to rebuild backlinks, tasks and search. It does not change any document, so it is safe to run whenever a sidebar disagrees with a document.

Scan for orphaned assets lists the images and files that no document refers to, so you can delete them. See Images And Files for more information.

Duplicate names

When two devices each create a page with the same name before they sync, the graph ends up with two documents under that name. Opening the name shows only one of them, which hides the other's text. Duplicates are usually pages, because two devices that start the same journal day write into one entry. See Working Offline for more information.

When you open a synced graph that has duplicate names, a dialog tells you how many there are. Review opens the Duplicate names section, and Not now hides the dialog until you next open the graph. The dialog waits until the graph has caught up with the Sync Server, so you do not see it while you are offline.

In either layout, the section lists each name with its documents under it, and gives each document's line count and first line. The longest document is the one kept unless you pick another with Keep this one. The kept document is listed first and marked Kept:. Show merged text previews the result: the kept text, then a blank line and the text below the frontmatter in each other document.

Merge… shows a line count for each document and asks you to confirm. It then adds the other documents' text to the kept one, which keeps its own frontmatter and collects the aliases of every document. The others are deleted only after the Sync Server has confirmed the added text, so a merge that stops deletes nothing, and merging again does not add any text twice.

A merge stops if you are offline, if a document changed after the section showed it, or if the Sync Server has not confirmed the text. A message under the name then tells you what to do.

A protected page is never merged: its row is marked protected, and Merge… and Show merged text are turned off.

Formatting scan

The scan under Formatting finds pages with text that the app reads one way and writes another, and groups them by check. You cannot use it in the phone layout, or when you open Settings from the Graphs page.

Check Fix
No-break spaces in indentation Replace each with a space.
Bullets written with * or + Change the marker to -. These bullets get no dot and no child bullets.
Indentation off the two-space grid Move tabs and uneven indentation onto the two-space grid, as an import does. Bullets can then nest as the author meant.
Missing blank line after a list Add a blank line before a line under a list that starts left of the bullet's text. Other Markdown apps read that line as part of the bullet.
Windows line endings End each line with a line feed.
Unclosed code blocks None. Use Open page and close or remove the fence by hand.

The fixes rewrite your pages and cannot be undone from Settings, so the scan stays off until you confirm that you have a backup. On a synced graph, Export… takes you to the Mirror and Export tab to export the graph. On a local graph, copy the folder or commit it to version control. Then type Export completed and checked (in any letter case, with or without single quotes) and press Scan for formatting issues.

The scan skips protected documents and pages that are still syncing on this device, and the results say how many it left out. It carries on after you close Settings, and the results stay until the next scan or until the graph closes.

Show changes shows each changed line both as it is now and as it will be, with no number on added lines. Invisible characters get a mark: → for a tab, · for an indentation space, ⍽ for a no-break or other special space, and ␍ for a carriage return.

Approve writes the fix, and Skip hides the issue until you press Show again. Once you have opened the changes for one page in a group, Approve all fixes every issue in that group that you have not yet approved or skipped, after you confirm the page count. A page edited since the scan is checked again rather than overwritten. Open page closes Settings and opens the page at the issue, and Back returns you to the results. See Document Syntax for more information.

Extensions and Install

The Extensions area has a switch for each extension, which applies to every graph on this device but not to other devices. See Extensions for more information.

In the Install area, you can install EtherPK on this device. See Installing EtherPK As An App for more information.

  • Code Maths And Diagrams
    • To give new blocks in a graph a language word, set Settings > General > Default code language. It applies only when you type nothing after the backticks. See Graph Settings for more information.
  • EtherPK On A Phone
    • The left drawer has tabs for The Graph Sidebar and Quick Notes. It is already open, over today's journal entry, the first time you open a graph on a device, and again after Reset workspace. The phone layout has no toolbar, so you open Graph Settings from Settings, a row at the bottom of the Graph Sidebar.
  • Glossary
    • | device setting | A setting kept only in this browser. It is never synced or exported. | Graph Settings |
    • | graph setting | A setting kept in the graph itself. It is the same for every member. | Graph Settings |
    • | Settings | The dialog for the open graph, titled Settings and Extensions. | Graph Settings |
  • Protected Documents
    • Binding needs the key itself, so the button is disabled while the graph is locked. See Graph Settings for more information on opening Settings.
  • Search
    • To rebuild the index yourself, go to Settings > Maintenance and select Rebuild search index. On a desktop, the cog in the toolbar opens Settings. Rebuilding does not change any of your documents, because the index is kept apart from them. See Graph Settings for more information.
  • Spell Check
    • Spell check has three settings, all on the Spelling tab in the Settings dialog (see Graph Settings). Turning spell check on or off affects every graph on the device. You choose the spelling languages separately for each graph on each device, so two devices, or two members of a shared graph, can check the same graph in different languages. The graph dictionary is part of the graph, so a word one member adds counts as correct for every member.
  • Tasks
    • The browser does not give EtherPK the folder's location, so the first time you copy an instruction on a device, EtherPK asks you for the path. Enter it and select Remember and copy, or select Skip and copy. If you skip, the text gives the file's location in the folder, such as pages/Beds.md, and EtherPK does not ask again on that device. You can set the path later in Folder path on this device (Graph Settings).
  • Templates
    • The Journal Template field does not appear when you open Settings from the Graphs page. See Graph Settings for more information.
  • The Graph Sidebar
    • Recents lists the documents you have opened on this device, newest first, one row each. It never syncs, so documents opened by another member, or by you on another device, do not change it. How many rows it shows is a graph setting, 10 by default. See Graph Settings for more information.
    • On a phone, select the Settings row to open the Settings and Extensions window. The sidebar has no such row on a desktop, where the cog button in the toolbar opens the same window. See Graph Settings for more information.
  • Troubleshooting
  • Using AI Agents With Your Notes
    • On a phone, select the Settings row at the foot of the Graph Sidebar, then choose Agents in the list of sections. See Graph Settings for more information.