EtherPK User Docs

Document Syntax

An EtherPK document, either a page or a journal entry, is GitHub-flavoured Markdown (GFM) plus wikilinks, task and free tags, highlighting, image size hints, named fenced blocks, frontmatter keys and Template variables.

A document's outline, tasks, links and journal days come only from its text. The editor and the Headless Client read that text by the same rules, so a file written outside EtherPK means exactly what its text says. A published site, though, reads some lines differently from the editor.

Indentation, blank lines and fence columns are all part of the syntax. Nothing inside a code block or inline code is markup. See Graph Folder Layout for the folder layout, file names and whitespace rules for editing by hand.

Blocks and lines

A bullet is a hyphen, a space and its text. Each nesting level is two spaces, and a child is exactly one level deeper than its parent. A line indented to the start of the bullet text continues that bullet. In this example, the blank line inside Garden holds two spaces:

- Garden
  plant the beans in rows
  - water the beans
    - check the soil
  
  a second paragraph of Garden
- Kitchen

A paragraph after the list.

A blank line at the margin ends the group of bullets. A blank line indented to the bullet text starts a new paragraph in the same bullet. A line at the margin directly under a bullet ends that bullet in EtherPK and on a published site, but other Markdown apps join it to the bullet. In files those apps open, leave a blank line above it.

Line Meaning
# to ######, then a space A heading. Blocks below nest under it until the next heading of the same or higher level.
Text with === or --- directly under it A level one or two heading that groups nothing
Plain text A paragraph. Lines below at the same indent join it.
> text A quote
* text, + text or 1. text A list item, kept as typed, with no dot, children or outliner keys. A published site shows it as a list.
*** or ___ alone, or --- after a blank line A horizontal rule
- --- A rule inside the bullet, which keeps its dot
A pipe table A GFM table. Two tables with no blank line between read as one.

See Outliner Blocks and Tables for more information.

Text styles

Text Meaning
**bold** or __bold__ Bold
*italic* or _italic_ Italic
~~struck~~ Strikethrough
==text== Highlight, with no space just inside the ==
^^text^^ Plain text, not Logseq's highlight
`code` Inline code
$x^2$ Inline maths, on one line
A $ with no closing $ on its line, or \$ A dollar sign

Other Markdown apps can show ==text== as typed. See Formatting Text for more information.

Text Meaning
[[Garden]] A link to the page or journal entry named Garden
[[[[Garden]] Beans]] A scoped link to Beans within Garden. Scopes nest to any depth.
[[2026-07-01]] A link to that day's journal entry, if the date is a real day
[text](https://example.com), <https://example.com> or a bare address A web link
file:///home/me/Seed%20List.pdf A file link, with spaces written as %20
![Garden](../assets/garden.png) An image from the assets folder
![Garden|300](…), ![Garden|640x480](…) An image at most 300 pixels wide, or 640 by 480, never enlarged
[Seed list](../assets/seed-list.pdf) A download link to a file in the assets folder
![Garden](https://example.com/garden.png) A web image, fetched from its site whenever it is shown

Everything inside the brackets, spaces included, is the page name, so [[Garden|text]] has no label and [[Garden#part]] does not link to a heading. Page names are not case-sensitive, so [[garden]] opens Garden.

Clicking a file link copies its path. The editor opens any other link with no scheme or with http:, https:, mailto:, tel: or ftp:. Links with other schemes stay plain text.

The editor shows an image as a picture only when nothing else shares its line, bullet or task, but a published site shows every image. See Pages And Wikilinks, Journal Entries, Scoped Concepts and Images And Files for more information.

Task tags

A task is a bullet with a checkbox: - [ ] for an open task, and - [x] or - [X] for a done one. Task tags go in a run straight after the checkbox:

- [ ] #P1 #D-2026-07-01 water the beans in [[Garden]] #weekly
Tag Meaning
#P1, #P2, #P3 Priority, with #P1 highest
#W, #D, #T Waiting, doing or test, on an open task
#C, #A Cancelled or archived, on a ticked task
#D-2026-07-01, #S-…, #C-… Due, scheduled or completed date
#weekly A free tag, which can go anywhere in the task. It uses only letters, digits and single hyphens, with at least one letter.

Task tags count only in that run, so a #P1 after a word is plain text. A free tag inside the run does not end it. Task tags are also case-sensitive, so #p1 is plain text and never a free tag.

The checkbox decides whether a task is finished, and a state tag that contradicts it has no effect. See Tasks for more information.

Fenced blocks

A fence opens with three or more backticks and an optional language or block name. It closes with the same number of backticks in the same column, so a block fenced with four backticks can hold a fence of three. Without a matching closing fence, the lines below are plain text in the editor but code on a published site. A published site also reads ~~~ as a fence, and the editor does not.

To put a fenced block in a bullet, indent the fence and its lines to the bullet text. You can also start the fence on the bullet line itself, as in - ```map.

Name Block
A language Highlighted code
math LaTeX maths. latex, tex and $$ blocks are not maths.
mermaid A Mermaid diagram
map A map of places and routes, one to a line
etherpk-cipher A protected document
An extension id, a dot and a name, such as excalidraw.drawing An extension block
An extension id alone, such as video An ordinary code block, editable by hand

In a map, a place line is a name, then @, then latitude and longitude in decimal degrees. A route line joins two or more points with >. A route from a GPX file ends with the path to its full recording in brackets. Leave that path in place.

- Garden plan
  ```map
  Shed @ 50.74860, -4.07890
  Path to the gate @ 50.74860, -4.07890 > 50.75112, -4.08240
  Morning walk @ 54.60120, -3.13410 > 54.60500, -3.14000 (../assets/morning-walk.a1b2c3d4.gpx)
  ```

Wikilinks inside a map are plain text. If EtherPK cannot read a line, it leaves the line as written and the map reports it.

The body of a protected document is a single etherpk-cipher fence of encrypted text below the frontmatter. Changing even one character makes the document unreadable for good. Adding text before or after the block ends the protection and leaves the encrypted text as plain text.

Change an extension block only through its extension, because the extension reads every line of it. Search skips the block. A published site shows a picture or link from the extension in its place, or shows nothing. See Code Maths And Diagrams, Drawings, Maps, Protected Documents and Extensions for more information.

Frontmatter

Frontmatter is a YAML block between the --- line at the top of the file and the next --- line. Indent it with two spaces. YAML does not allow tabs, so EtherPK ignores the whole block if it is indented with a tab. Put each list item on its own line, even in a list of one:

---
title: Garden
aliases:
  - Vegetable Patch
public: true
publications:
  - garden-notes
status: draft
---
Key Meaning
title The page name, or the file name when it is missing. A journal entry ignores it.
aliases Other names for the page
public true allows publishing. "true" in quotes does not.
publications A list of publication ids. A bare id names no publication.
publication Makes the page a publication's settings page, whose keys are on Publish Settings
slug The address on a published site, instead of one from the name
date A blog post's date, as YYYY-MM-DD, on pages only
template true makes the page a Template. A journal entry is never one.

Keys of your own stay as you wrote them, and Search can filter by them, as in status:draft. A key with an empty value counts as not set. See Titles Aliases And Frontmatter for more information.

Template variables

Variables are filled in only in a copy of a Template, so the Template itself and a published site show them as typed. A day variable gives the day of the journal entry it is copied into, or today's date in any other document.

Variable Gives
{{date}}, {{today}}, {{yesterday}}, {{tomorrow}} A link to the day, or the day before or after, as [[YYYY-MM-DD]]
{{time}}, {{datetime}} HH:mm or YYYY-MM-DD HH:mm, as plain text
{{title}} The document's name, or the day in a journal entry, as plain text. Link it as [[{{title}}]].
{{date:DD/MM/YYYY}}, {{time:HH:mm}} The day or time in that format, with no link. Tokens: YYYY, YY, MM, DD, HH, mm, ss, case-sensitive.
{{cursor}} Where the cursor goes after the copy
\{{date}} {{date}} as typed, without the backslash
An unknown name, such as {{dat}} The variable as written

Inside a wikilink, a day variable gives just the date, with no link of its own, so [[{{date}} harvest]] makes one link. See Templates for more information.

  • Graph Settings
    • 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.
  • Tables
  • Templates
  • Using AI Agents With Your Notes
    • AGENTS.md gives the agent the file format, how notes are written, and what to leave alone. See Document Syntax for more information.