Wikilinks | Grafos

Obsidian-compatible wikilink syntax for linking between pages, headings, and embedding content.

Grafos supports Obsidian-compatible wikilink syntax for linking between pages. Wikilinks are a concise alternative to standard markdown links that use double brackets instead of the [text](url) format.

Syntax

The basic wikilink syntax is a page slug inside double brackets:

Check the [[installation]] guide.

This renders as a link to the page at content/installation.md with the page's title as the link text.

Wikilinks support several variants:

Basic page link — links to a page using its slug:

[[installation]]

Aliased link — displays custom text instead of the page title:

[[installation|Install Grafos]]

Heading link — links to a specific heading on a page:

[[configuration#feature-flags]]

Heading link with alias — custom text linking to a specific heading:

[[configuration#feature-flags|feature toggles]]

Embed — embeds the content of another page inline. Uses the ! prefix:

![[quick-start]]

Embeds pull in the full rendered content of the target page. They are useful for reusing content across multiple pages without duplication.

The wikilink syntax in Grafos matches Obsidian's implementation. If you author content in Obsidian and publish with Grafos, your links work without modification.

Aliases

Aliases let you reference a page by alternative names. Define them in the page's frontmatter:

---
title: Configuration
aliases: [config, settings, options]
---

With these aliases defined, all of the following wikilinks resolve to the same page:

[[configuration]]  -> content/configuration.md
[[config]]         -> content/configuration.md
[[settings]]       -> content/configuration.md
[[options]]        -> content/configuration.md

Aliases are resolved during the pre-build step. The manifest records each alias and maps it to the canonical slug. At render time, the remark-wikilinks plugin looks up the target in the manifest and generates the correct URL.

Aliases are also used for backlinks tracking. A link via [[config]] creates the same backlink connection as [[configuration]].

If you rename a file, add the old filename as an alias to preserve existing wikilinks. For example, if you rename setup.md to installation.md, add aliases: [setup] to the new file's frontmatter.

Resolution

Wikilinks are resolved in the following order:

Exact slug match — the link target matches a file's slug (filename without .md)
Alias match — the link target matches an alias defined in a page's frontmatter
Case-insensitive match — the link target matches a slug or alias regardless of case
Path match — for files in subdirectories, both the full path (guides/deploy) and the filename alone (deploy) are checked

If a wikilink cannot be resolved, it renders as plain text with a distinct "broken link" style (red with a dashed underline) so you can spot and fix it during development.

[[nonexistent-page]]  -> renders as broken link

During the pre-build step, Grafos logs all unresolved wikilinks to the console. This makes it easy to find broken links when you rename or delete pages.

For pages in nested folders (see content-directory), you can use either the full path or just the filename:

[[guides/deploy]]  -> content/guides/deploy.md (full path)
[[deploy]]         -> content/guides/deploy.md (filename match)

If multiple files share the same filename in different folders, use the full path to disambiguate. If you use just the filename, Grafos resolves to the first match and logs a warning about the ambiguity.