Magic Links (Wiki Links)
updated
Magic links let you navigate between documents using aliases, with autocomplete and built-in link validation.
Syntax
Use double brackets to link to a document by its alias:
[[getting-started]]
Add a display label with the pipe | separator:
[[api-reference|API Documentation]]
This displays “API Documentation” but navigates to the api-reference document.
Cross-project links
Use double colons :: to link to a document in another project:
[[design-system::button-component|Button Component Docs]]
Note: Cross-project links only work within the same workspace.
All formats
| Format | Syntax | Displays |
|---|---|---|
| Simple | [[alias]] |
alias |
| With label | [[alias|Label]] |
Label |
| Cross-project | [[project::alias]] |
project::alias |
| Cross-project with label | [[project::alias|Label]] |
Label |
Autocomplete
Type [[ to open an autocomplete dropdown with available documents. Filter by typing, navigate with arrow keys, and press Enter or Tab to insert. Press Escape to cancel without inserting a link.
Link appearance
In edit mode, you see the full syntax: [[getting-started|Getting Started Guide]]. In preview mode, the brackets and alias are hidden — only the display text appears as a styled link.
Link validation
The editor validates wiki links automatically. Valid links show normal styling. Broken links (where the target doesn’t exist) are highlighted so you can fix them. Cross-project links show a distinct indicator.
When magic links are not extracted
To keep examples in your docs from being treated as real links, magic links are ignored when they appear inside:
- Inline code —
`[[example-alias]]`(single, double, or triple backticks) - Fenced code blocks — both
```and~~~fences, including fences indented inside list items and nested fences (a 3-backtick block inside a 4-backtick block) - Escaped brackets — write
\[\[example-alias\]\]to render the syntax literally without creating a link
The same rules apply to standard Markdown links [text](url).
Magic links vs. Markdown links
| Feature | Magic links [[...]] |
Markdown links [...](...) |
|---|---|---|
| Target | Document alias | URL or path |
| Autocomplete | Yes | No |
| Validation | Yes | No |
| Cross-project | Yes | No |
| Best for | Internal navigation | External URLs |
What’s next?
Supported Markdown Syntax — Full reference for supported Markdown syntax.
Working with Documents — Write and format content in the editor.