Anchor

Anchor syntax ($my-anchor) gives the containing Object a stable, (potentially) meaningful, space-globally unique name. That name becomes the object’s ref, and it can be linked to from any page using [[$my-anchor]].

Anchors are an alternative to position-based refs (Page@123) and header refs (Page#Section): they survive edits to the page (positions shift, anchors do not), and unlike header refs they don’t collide when two sections share a title.

Scope rules

Like Hashtags, an $anchor attaches to its closest containing object:

• In a paragraph, it attaches to the paragraph.
• In a bullet, it attaches to that item.
• In a Task, it attaches to that task.
• In a header, it attaches to that header.
• In a Markdown/Fenced Code Block with a #tag as language, the anchor is set via a YAML field named $ref: inside the block (the markdown anchor syntax doesn’t apply inside YAML).
• In Frontmatter, a $ref: field gives the page itself a memorable anchor (e.g. $ref: today lets you jump to a long, dated page name from anywhere with [[$today]]).

Examples

A paragraph with an anchor $para-anchor here.

• Item with anchor $first-item
• Task with anchor $first-task

Header with anchor $sec1

name: Pete
$ref: pete

In addition, all anchors are queryable via anchor:

${queryfrom o = index.objects(“anchor”)}

Linking

Anchors are referenced from a Link just like a page or header:

• [[$my-anchor]] — bare, resolves space-globally.
• [[Some Page$my-anchor]] — page-qualified (useful while a duplicate is being resolved, or for explicitness).
• ![[$my-anchor]] — transcludes just the anchored object (paragraph, task, item, etc.), not the whole page.

Anchors are also directly reachable from the Page Picker: open it and type $ to search anchors across your space.

Effect on objects

The anchor name replaces the default ref for the object that contains it. For instance, * [ ] $tsk1 Pay rent produces a task object with ref: "tsk1" (instead of the usual Page@<pos>).

For page-level anchors (frontmatter $ref:), the page object’s ref is left untouched (so existing page lookups by name keep working) — instead, a parallel anchor record points back to the page. See Object and anchor for details.

Naming rules

Anchor names can contain letters, digits, dashes, underscores, slashes, and colons, but:

• Must not start with a digit (so $100 is not an anchor — handy for amounts).
• Must not contain whitespace, periods, or other punctuation. Periods are excluded so a sentence-ending period after an anchor (The $tsk1.) is not consumed into the name.

The grammar is $ followed by [A-Za-z_][A-Za-z0-9_/:-]*.

Uniqueness

Anchor names must be globally unique within your Space. Editor-based linting will highlight broken links, and multiple anchors in the same object. The contract is enforced by lint, not by the indexer — when duplicates briefly exist (for instance, while you are renaming one), both stay indexed and lint surfaces the issue at edit time.