docs/user/features/wikilinks.md
Wikilinks are internal links that connect files in your knowledge base using [[double bracket]] syntax.
[[ and start typing a note nameTabCtrl+Click (Cmd+Click on Mac) or F12Example: [graph-view]
Wikilinks to non-existent files create placeholder links, styled differently to show they need files created. They're useful for planning your knowledge structure.
View placeholders in the graph with Foam: Show Graph command or in the Placeholders panel.
Link to specific sections using [[note-name#Section Title]] syntax. Foam provides autocomplete for section titles.
Examples:
[link text](other-file.md#section-name)[link text](#section-name)Link to a specific paragraph, list item, heading, or blockquote using [[note-name#^blockid]] syntax. Add a ^your-id anchor at the end of any block element, then reference it from other notes.
See [block-anchors] for full details.
Linking to a folder name navigates to that folder's index file — either index.md or README.md. This works for both wikilinks and regular markdown links:
[[projects]] → opens projects/index.md (or projects/README.md)[Projects](projects) → same[Projects](projects/) → trailing slash is ignoredIf a file named projects.md exists alongside the projects/ folder, it takes priority.
To disable this behavior, set foam.links.directory.mode to disabled in your VS Code settings.
When you rename or move a note or folder, Foam automatically updates all wikilinks pointing to it. This is enabled by default and can be turned off via the foam.links.sync.enable setting.
For standard markdown links (e.g. [text](path/to/note.md)), VS Code has a built-in feature that handles this. Enable it in VS Code settings: set markdown.updateLinksOnFileMove.enabled to always or prompt.
Wikilinks come in two forms:
[[filename]], [[folder/filename]] — identify a resource by name, resolved relative to the whole workspace[[./file]], [[../other/file]], [[/from/root]] — identify a resource by its file pathThe rule: if the link starts with / or ., it's a path reference; otherwise it's an identifier.
For identifier links, you can use any suffix that uniquely identifies the file. Given projects/house/todo.md and work/todo.md, the identifiers [[todo]] (ambiguous), [[house/todo]] (unique), and [[projects/house/todo]] (unique) are all valid — Foam picks the shortest unambiguous form.
When the same filename exists in multiple locations, [[todo]] is ambiguous. Foam resolves it alphabetically (deterministic), and shows a warning diagnostic so you can use a more specific identifier like [[house/todo]].
Foam can automatically generate [link-reference-definitions] at the bottom of files to make wikilinks compatible with standard Markdown processors.
| Wikilink | Obsidian | Foam |
|---|---|---|
[[notes]] | ✔ unique identifier in repo | ✔ unique identifier in repo |
[[/work/notes]] | ✔ valid path from repo root | ✔ valid path from repo root |
[[work/notes]] | ✔ valid path from repo root | ✔ valid identifier in repo |
[[project/house/todo]] | ✔ valid path from repo root | ✔ valid unique identifier |
[[/project/house/todo]] | ✔ valid path from repo root | ✔ valid path from repo root |
[[house/todo]] | ✔ valid unique identifier | ✔ valid unique identifier |
[[todo]] (ambiguous) | ✘ ambiguous identifier | ✘ ambiguous identifier |
[[/house/todo]] (wrong path) | ✘ incorrect path from repo root | ✘ incorrect path from repo root |