A wiki-link points from one file to another by name: `[[Design Notes]]`. It is plain text in your markdown, it autocompletes as you type, and Monofile indexes it so the target file lists it as a backlink.
## Writing a link
```md
See [[Design Notes]] before you start.
The [[Design Notes|original sketches]] explain why.
```
The first form shows the target's name as the link text. The second form shows your own words and keeps the target on the left of the pipe. The syntax is a target, an optional `|alias`, and closing brackets.
## Autocomplete
Type `[[` in a markdown file and a menu opens over your files. It matches your query against both the file name and its path, puts markdown files first, and shows up to eight results with the name on top and the path underneath.
| Key | Action |
|---|---|
| Type | Filter the list |
| ↑ and ↓ | Move through results |
| Enter | Insert the selected link |
| Escape | Close the menu |
Selecting a result inserts the file name with its extension, so picking `Design Notes.md` writes `[[Design Notes.md]]`. A name stays valid when the file moves between folders. The menu cannot create a new file. If the file does not exist yet, type the link anyway and create the file later.
## How a target resolves
| Target | How it is matched |
|---|---|
| `[[Design Notes]]` | Case-insensitive match on file name, with or without `.md`. `[[note]]`, `[[Note]]` and `[[Note.md]]` all find `Note.md` |
| `[[projects/q3/plan.md]]` | Anything containing a slash matches as a full path, case-sensitively |
Resolution stays inside your workspace. A link cannot reach a file in another person's workspace or in a different team space. If two files match the same bare name, Monofile picks the one nearest the root, then the one edited most recently. It does not show an ambiguity error.
Monofile scans `.md`, `.mdx` and `.txt` files for links. It ignores links inside a fenced code block or inline code, so documenting the syntax does not create a link.
## Links that survive a move
A bare link matches on name, so moving a file does not break it. Move `Note.md` from `inbox/` to `archive/2026/` and every `[[Note]]` pointing at it keeps working without a rewrite.
> [!WARNING]
> Renaming does break links. A link is text and Monofile does not rewrite your files, so after you rename `Note.md` to `Meeting Notes.md`, the text `[[Note]]` matches nothing and renders as unresolved. The backlink on the renamed file stays visible until the linking file is next saved. For a file linked from many places, link with an alias from the start. `[[Meeting Notes|the notes]]` lets you change the display text and the target independently.
## When a link does not resolve
An unresolved link renders as a muted chip with a dashed underline, and clicking it does nothing. Hover it and you see "No matching doc".
You can link to a file before it exists. Write `[[Rollout Plan]]` in today's note, and the moment you create a file with that name, the chip resolves and the backlink appears on the new file. The linking file does not need another save, because resolution happens at render time.
## Stored as plain markdown
A wiki-link lives in your file as literal `[[...]]` text. The file reads correctly in any markdown tool, and an agent can create links with an ordinary text edit through the API or the CLI. Agent writes go through the same indexing as yours, so agent-authored links show up in your backlinks immediately.
## Next steps
:::cards
- [[Backlinks and Graph]] — See what links to a file, and navigate your workspace as a graph.
- [[Markdown Reference]] — Every markdown feature Monofile renders, with examples.
- [[The Markdown Editor]] — Live WYSIWYG editing, slash commands, and how saving works.
- [[Files and Folders]] — Paths, the file tree, renaming, moving, deleting and restoring.
:::