Wiki links

Link pages with [[wiki link]] syntax, follow backlinks, and move pages without breaking links.

Wiki links connect pages with [[double brackets]]. KiwiFS indexes every link, so each page knows what links to it, the knowledge graph stays current, and moving a page rewrites the links that point at it.

concepts/tokens.md

See [[authentication]] for how tokens are validated.

Related: [[concepts/rate-limiting|Rate limiting]] and [[../runbooks/rotate-keys]].

Syntax

Syntax	Links to
[[note]]	The page whose file name is note.md
[[folder/note]]	A page by path
[[/folder/note]]	A path from the knowledge base root, always
[[./note]], [[../up/note]]	A path relative to the current page’s folder
[[note|Label]]	The same target, shown as “Label”
[[note#Heading]]	The page note.md; the heading is an anchor

The .md extension is optional. Matching ignores case and treats -, _, and spaces as the same, so [[Rate Limiting]] finds rate-limiting.md.

Links inside code blocks and inline code are plain text, not links.

How links resolve

A bare name matches a file name exactly. There is no prefix guessing: [[auth]] does not find authentication.md.

When more than one file has the same name, KiwiFS picks one in this order:

1. The file in the same folder as the linking page.
2. The file with the shortest path.
3. The alphabetically first path.

A link with a slash, such as [[folder/note]], is tried from the root first, then relative to the linking page’s folder, then as a unique path suffix anywhere in the knowledge base.

The web UI, backlinks, the graph, and DQL all use the same rules, so a link points at the same page everywhere.

Links in frontmatter

Frontmatter fields can hold typed links. By default, contradicts, supersedes, and superseded_by are indexed as links with that relation. Add your own fields in config:

.kiwi/config.toml

[links]
typed_fields = ["contradicts", "supersedes", "superseded_by", "related-notes"]

Values can be plain paths or wiki links:

related-notes:
  - concepts/caching.md
  - "[[concepts/rate-limiting]]"

Typed links appear in backlinks with their relation, and DQL’s rollup() can follow them.

Backlinks

Every page shows a Backlinks panel listing the pages that link to it.

Terminal

curl 'http://localhost:3333/api/kiwi/backlinks?path=concepts/authentication.md'

The response lists each linking page, with its relation for typed links. Over MCP, call kiwi_backlinks.

Move pages without breaking links

Renaming or moving a page through KiwiFS rewrites every wiki link and markdown link that pointed at it. The move and every relinked page land in one commit, and the rename fails with 409 instead of leaving a link behind.

Interface	Single move	Several moves, folders, or merges
REST	POST /api/kiwi/rename	POST /api/kiwi/refactor/plan, then /refactor/apply
MCP	kiwi_rename	kiwi_refactor_plan, then kiwi_refactor_apply
CLI		kiwifs refactor plan, then kiwifs refactor apply

See Refactor for plans, merges, and reverting a restructuring.

Broken links and orphans

A link that resolves to nothing is styled as missing in the web UI. Click it to create the page.

Check	REST	CLI
Broken links	GET /api/kiwi/links/broken	kiwifs lint, kiwifs check
Orphans (no inbound links)	GET /api/kiwi/links/orphans	kiwifs check
Repair broken links	POST /api/kiwi/refactor/fix-broken

Broken links never stop a page from rendering. See the Refactor API for these endpoints.

Knowledge graph

The web UI’s graph view draws every page as a node and every link as an edge, in 2D or 3D. You can filter by folder or tag and find the shortest path between two pages.

Terminal

curl 'http://localhost:3333/api/kiwi/graph'

The response has nodes (pages with their tags) and edges (raw link pairs). For centrality, communities, shortest paths, and local neighborhoods, see the graph APIs.

Related

Refactor

Move, merge, and restructure pages safely.

Metadata API

Backlinks and graph endpoints.

DQL

Query links with rollup() and _backlink_count.

Web UI

Graph view, backlinks panel, and the editor.