Wikilinks, backlinks, and the graph
Wikilinks, backlinks, and the graph
Lettuce’s most useful affordance is its first-class link graph. Every [[wikilink]] you write becomes an edge that powers backlinks, the graph view, smart rename, and several agent tools.
Wikilink syntax
| Form | Resolves to |
|---|---|
[[note]] |
Any note named note.md in the vault |
[[Folder/note]] |
Specifically Folder/note.md |
[[note|alias]] |
Renders as “alias”, links to note.md |
[[note#section]] |
Jumps to the ## section heading |
[[note#^block-id]] |
Jumps to a block-id |
[[#section]] |
Section within the current note |
Resolution rules:
Exact filename match, case-insensitive (full vault-relative path or basename).
If a basename is ambiguous (same name in several folders), the copy in the same folder as the linking note wins, else the shortest path.
A fuzzy match is offered only in the editor’s autocomplete — never auto-resolved at link-follow time.
aliases: in frontmatter are recorded (and surfaced in search) but are not currently used to resolve [[wikilinks]] — link by filename.
Backlinks
The inspector’s Backlinks tab shows every note that links to the current one, with a preview of each link’s surrounding paragraph. Click any backlink to jump.
Backlinks include:
Direct
[[name]]linksAliased links (
[[name|alias]])Block references (
[[name#^id]])Section references (
[[name#heading]])Plain Markdown links to the note (
[text](path.md))
Backlinks are always live — change a wikilink anywhere and the count updates within milliseconds.
The graph
View → Graph (or ⌘G) opens a force-directed visualisation. Nodes are notes; edges are wikilinks. The view has three controls:
Scope toggle — “This note” shows the local subgraph around the selected note; “Whole vault” shows everything.
Show tags — overlays tag nodes so you can see notes clustered by
#tagas well as by link.Popout — open the graph in its own roomy window for exploring large vaults.
Useful for:
Finding orphans — notes nothing points at appear as disconnected nodes.
lint’sno-inboundrule flags these deterministically; itsorphan-noterule flags notes with no links in or out.Cluster discovery — visually obvious groupings reveal informal topic boundaries.
Hub identification — large-degree nodes are usually concept notes worth investing in.
Smart rename
Rename a note in Lettuce (sidebar context menu → Rename, or just double-click) and every wikilink to it is rewritten:
[[old name]]→[[new name]][[Folder/old name]]→[[Folder/new name]][[old name|alias]]→[[new name|alias]](alias preserved)[[old name#section]]→[[new name#section]]
The rewrite is atomic: either all references update or none do. There’s a confirmation dialog showing every file that will change.
If you rename a file outside Lettuce (Finder, git mv, agents using raw write_note instead of apply_edits), the wikilinks don’t auto-update — you’ll get broken links until you fix them.
Programmatic access
Agents can read the link graph two ways:
read_outline(note: "Lettuce.md")
→ returns headings + outgoing links in document order
link_graph(seed: "Lettuce.md", depth: 2)
→ returns the subgraph reachable within 2 hops
See Agent reference/04 Read tools for full signatures.
Performance
The link index is built in parallel at launch and updated incrementally on each save. On a 6000-note vault, full rebuild takes <100ms; incremental updates are sub-millisecond. See For developers/04 Architecture map for the details.
Related
Core concepts/05 Tags — tags as a complementary connection mechanism
Core concepts/09 Block IDs and references — sub-paragraph links
Agent reference/04 Read tools —
link_graphtool