62 lines
3.3 KiB
Markdown
62 lines
3.3 KiB
Markdown
---
|
|
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]]`.
|
|
|
|
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]] 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
|
|
|
|
```#person
|
|
name: Pete
|
|
$ref: pete
|
|
```
|
|
|
|
In addition, all anchors are queryable via [[Object/anchor]]:
|
|
|
|
${query[[from 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]]` — [[Transclusions|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 [[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.
|