description: "An inline $anchor that gives an object a space-globally unique name." tags: glossary maturity/experimental references:

  • plugs/index/anchor.ts
  • client/markdown_parser/constants.ts

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]($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 Markdown/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](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]($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 Object/anchor:

${query[from o = index.objects("anchor")](from o = index.objects("anchor"))}

Linking

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

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

Anchors are also directly reachable from the [Page Picker](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 Object/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.