Linking notes

Linking notes

Links in track are explicit: you write [[Title]] in a note body to point at another note. There is no implicit auto-linking of bare words — a link exists only where you wrote one.

Link syntax

A title is the resolution key, and titles come from each note's metadata — editing a body heading does not rename a note. Use track rename to change a title and rewrite the backlinks that point to it.

Backlinks and the graph

Because links are explicit and indexed, track can answer the reverse question: which notes point here? That is what track backlinks and the Web workspace backlinks panel show. track graph returns the local neighbourhood of a note as nodes and edges.

Beside those, a note's aside opens with Contents: its heading outline, indented by level, each entry jumping to that heading. It appears on any note with more than one heading, in the workspace and on a published site alike, and needs nothing written in the note — the headings are the outline.

On wide windows, the note's tags, Contents, backlinks, and local graph sit at the right edge of the reading surface, even when the text column is narrow. The text keeps its selected Content width in the remaining space. The aside stays visible while the note scrolls; on narrow windows and in split/edit view, it returns below the note so the columns do not overlap.

In the static export

When you publish with track export-site, a [[...]] link becomes a real anchor only when its target is part of the published set. Links to notes outside the selection are flattened to plain text, so the exported site never has dangling links. See CLI for the export commands.

Titles with square brackets

Keep balanced square brackets in the title when writing a wiki link. For a note titled [test], write [[[test]]]. Nested brackets work too: a note titled Plan [draft [v2]] is linked as [[Plan [draft [v2]]]]. Aliases can also contain balanced brackets, such as [[[test]|Example [draft]]]. These links resolve, appear in backlinks, and follow title renames just like other wiki links. The same title syntax works in an include, for example ![[[test]]] on its own line.

Brackets inside a wiki link must be balanced; an unmatched bracket is not a valid link. No extra backslash escaping is needed for balanced brackets. The title stored in the note's metadata stays unchanged.

Opt-in stable ID targets

To separate a note's identity from its title, set link_format: id-v1 in that vault's .track/config.yml. Leave the key absent, or set it to title, to retain title-only interpretation. Existing vaults are not converted or enabled automatically.

In ID mode, a reference can store the note ID while showing a readable label:

[[id:1785024000000|Readable title]]
[[id:1785024000000##Design|Design section]]
[[id:1785024000000#^block-1|Relevant block]]
[[work:id:1785024000000|A note in work]]
![[id:1785024000000|Embedded note]]

Replace the example ID with the actual target's ID. work must be a registered vault. IDs are local to a vault: the same number in another vault is a different note. The source vault selects the syntax; the referenced vault does not need to enable ID mode. The target ID does not change when its title changes. An explicit display label is authored text and stays as written, even if it becomes an old title.

Legacy [[Title]] links continue to resolve in ID mode. A bare [[123]] still means the title 123, not ID 123. Explicit missing or malformed ID targets do not fall back to a title. Existing HTTP(S) URLs and asset links are unaffected.

ID mode reserves id: target spellings. A vault registered as id, or a note title beginning with id: or containing :id:, blocks this mode with an error. Resolve the collision explicitly or leave the vault in title mode; Track never renames those titles or rewrites body links automatically. A cross-vault ID target that also matches a literal ID-shaped title in the target vault is rejected as ambiguous instead of silently changing an old title link. Resolve that collision explicitly. An unavailable remote target stays unresolved without blocking unrelated local editing. Target vaults need not enable ID mode. Local validation also protects against later synced reserved titles. Title uniqueness checks remain in place; enabling ID links does not permit duplicate titles.

There is no automatic link migration. Keep existing links, or edit selected links after checking their intended target. Renaming an ID-linked note does not rewrite its ID target or explicit label. Heading and block anchors can still become invalid when their own text or marker changes. The ID stabilizes the note, not every position inside it.

For an included note, use an explicit |label when you want a title caption: the initial ID mode leaves an unlabelled include caption as its ID target. The included content still resolves by stable identity.