Titles, aliases and frontmatter

The block at the very top of a document, between two lines of ---, is its frontmatter. It holds a few settings written as key: value lines. This page says what those settings do, which ones EtherPK acts on, and how that differs between a local graph and a synced one.

---
title: Kanban
aliases:
  - Board
  - Kanban wall
---
- the document starts here

You can type into the block like any other text. It's shown in a shaded panel, and the outliner leaves it alone - a - line inside it is a list entry in the settings, not a bullet.

What the settings do

Setting What it does Local graph Synced graph
title The document's name - what links point at, what the tab says. Changing it here is a rename, with a confirmation (below). Deleting it names the document after its file. The same confirmation; the name lives with the graph and the block is asking to change it.
aliases Other names the document answers to. [[Board]] opens Kanban. Applied when you leave the block. Applied when you leave the block.
public Reserved for publishing. Kept, does nothing yet. Kept, does nothing yet.
anything else Yours. EtherPK keeps it exactly as you wrote it and doesn't read it.

A journal entry is named by its date, so a title in one is kept but does nothing; aliases work there as they do on a page.

Changing the title

Edit the title: line and then leave the block - move the caret below it, click somewhere else, or close the document. The Rename dialog opens with your new name already filled in, exactly as if you'd chosen Rename… from the tab. It tells you how many documents link to the old name and lets you choose whether to keep the old name as an alias or rewrite those links.

Cancel puts the old title back in the block. Nothing changes until you confirm - on a local graph the file on disk keeps the old title the whole time you're typing.

If the name you typed belongs to a protected document, there's no dialog: EtherPK tells you it can't rename onto a protected page and puts the old title back. See Protecting Sensitive Documents.

You don't have to find the page's tab to rename it. Right-click any [[link]] in a document (or press and hold it on a phone) and choose Rename…: the same dialog opens for the link's name, whether or not a page exists for it yet.

Editing the link's text in place does the same thing. Put the caret inside a link (Ctrl+click on a desktop) and change what it says; when the caret leaves the link, EtherPK notices that the old name is still used elsewhere - by a page, or by other links - and asks whether to rename it everywhere. Choose Just this link and nothing else changes: the link says what you typed, and now points at that name instead. If the old name isn't used anywhere else, nothing is asked. In a nested link like [[[[Physics]] Quantum]], editing the inner part is about "Physics" and editing the outer part is about "Physics Quantum".

A rename never moves you. Whichever way you asked for it, the tabs you had open stay open under their new names, in the same places, and the one you were looking at is still the one in front. A page named with a scope - Fishing for [[Lifeyx]] - is renamed along with the scope, so links to it keep working.

The block keeps its edges

Pressing Backspace at the start of the first line under the block, or Delete at the end of its closing ---, is refused, and a short message says why. The same goes for deleting or typing over a selection that runs from inside the block into the text below it. Joining the two would break the closing line, and at that point the block is no longer frontmatter - the title: line becomes ordinary text. The message sits at the foot of the page and goes on its own once you carry on typing. You can still edit anything inside the block, and delete the block whole if you select it all.

Changing aliases

Edit the aliases: list and leave the block. That's it - no dialog. Blank entries and duplicates are dropped, and a document is never its own alias. Removing the aliases: line removes them all.

When the block and the name disagree

On a synced graph you might open a document whose block says one title while the tab says another. It happens when someone changed the block on a device that never answered the rename question, or when two people renamed the same document at the same moment. The document answers to the name on the tab, and a small note on the block's first line says so, with two buttons:

The note hides while you're typing in the block and comes back when you leave it.

Editing the file outside EtherPK

On a local graph you can change the block in another editor too. Change the title there and EtherPK treats it as a rename that has already happened: within a few seconds the open tab follows the file to its new name, and you'll see a short notice. Links to the old name aren't updated for you - the other editor didn't do that either - so use Rename… in EtherPK when you want them rewritten.

Protected documents

The block is the part of a protected document that is not scrambled, so you can edit it whether the document is locked or unlocked, and a changed title goes through the same rename confirmation. The one thing you can't do is delete the block from a protected document: without it the title line would be sealed in with the secret at the next save. See Protecting Sensitive Documents.

See also