Links & Popovers

DocAnvil provides two special inline syntaxes beyond standard Markdown: wiki-links for linking between pages and popovers for inline tooltips.

Wiki-Links

Wiki-links are DocAnvil's built-in cross-page linking syntax — they resolve slugs automatically and warn you about broken references at build time.

Basic Syntax

Link to another page using double brackets:

See [[guides/getting-started]] for installation steps.

This resolves to an HTML link pointing at the target page. The display text defaults to the link target.

Custom Display Text

Use a pipe to set custom link text:

Check the [[guides/getting-started|installation guide]] to get started.

Live Examples

Here are working wiki-links to pages in this documentation:

• index — the home page
• Configuration guide — customizing your project
• CLI reference — all commands and flags
• Markdown features — supported syntax

Resolution Rules

DocAnvil resolves wiki-links against the page inventory in three steps:

1. Exact match — the target is compared to page slugs directly (guides/getting-started matches guides/getting-started)
2. Alias match — if a page's slug was overridden by front matter (via title or slug), the old filename-based slug still resolves to the new page
3. Basename match — if no exact or alias match, the last path component is tried (getting-started matches guides/getting-started)

Basename matching means you can use short names when the page name is unique:

[[getting-started]]     resolves to → guides/getting-started
[[configuration]]       resolves to → guides/configuration

Slug Derivation

Slugs are derived from the file path relative to the content directory, with the .md extension removed. When a page has a title or slug in its front matter, the slug is overridden accordingly.

When a slug changes, both the old and new slugs resolve correctly in wiki-links.

Locale-Aware Resolution

When localisation is enabled, wiki-links resolve within the same locale. A link like getting-started in a French page points to the French version of that page — you don't need to specify the locale in your links. This means your content can be translated independently without changing any wiki-links.

Broken Links

When a wiki-link target doesn't match any page, it renders as a red highlighted span with an error popover. Here is a deliberate example:

nonexistent-page Page not found
The linked page doesn't exist: nonexistent-page

The build process also logs a warning for each broken link, so you can find and fix them.

Popovers

Popovers add inline tooltip content that appears on hover or focus.

Syntax

Use ^[content] to create a popover:

DocAnvil uses comrak^[A fast, GFM-compatible Markdown parser written in Rust] for rendering.

Live Popover Examples

DocAnvil uses comrakA fast, GFM-compatible Markdown parser written in Rust for rendering Markdown.

The default theme uses an indigoSpecifically #6366f1, a balanced purple-blue accent color.

Popovers appear above the trigger text by default, but flip belowThis automatic repositioning prevents popovers from being clipped at the top of the viewport when near the top of the viewport.

Behavior

• Popovers appear on hover and keyboard focus
• They automatically reposition to avoid overflowing viewport edges
• Content inside backticks (`) and fenced code blocks is not processed
• HTML in popover content is escaped for safety

Skipped in Code

Popover syntax inside inline code (^[like this]) and fenced code blocks is left as-is:

This ^[popover syntax] is not processed inside code blocks.

Related Pages

• Markdown — all supported Markdown and GFM features
• Components — directive blocks for richer content