Linking & Referencing
docmd provides a filesystem-aware linking system. Write links referencing source .md files naturally, the compiler normalises target paths into clean, canonical URLs automatically.
Write target paths using .md extensions, trailing slashes, or direct filenames (overview.md, overview/, or overview). The build compiler resolves them to identical canonical URLs.
URL Normalisation Mechanics
During build compilation, docmd normalises internal link targets automatically across Markdown prose, button containers, tags, and navigation trees:
| Input Path | Compiled Output URL | Resolution Rule |
|---|---|---|
overview.md |
overview/ |
Strips .md extension, appends trailing /. |
overview |
overview/ |
Appends trailing / automatically. |
overview/ |
overview/ |
Retains existing canonical format. |
release-1.0.md |
release-1.0/ |
Preserves dots in page filenames. |
api/commands.md |
api/commands/ |
Normalises subdirectory route. |
localisation/index.md |
localisation/ |
Strips index, resolves directory root. |
../index.md |
../ |
Resolves parent directory root. |
overview.md#settings |
overview/#settings |
Preserves URL hash fragment. |
api.md?tab=curl |
api/?tab=curl |
Preserves query strings across depth shifts. |
https://example.com |
https://example.com |
Retains external URL untouched. |
Internal Document Links
Reference internal documents using relative filesystem paths:
| Link Target | Syntax Example |
|---|---|
| Sibling Page | [System Overview](overview.md) |
| Filenames with Dots | [Release 1.0 Milestone](release-1.0.md) |
| Subdirectory Page | [API Reference](api/node-api.md) |
| Directory Index | [Localisation](localisation/index.md) |
| Parent Directory | [Back to Home](../index.md) |
| Page with Query Strings | [Install Command](install.md?tab=docker) |
Section Anchor Links
Navigate to specific document headings using URL hash fragments:
<!-- Intra-page section anchor -->
[Jump to Roadmap](#project-roadmap)
<!-- Cross-page section anchor -->
[Review CLI Flags](../api/cli-commands.md#available-flags)
Hash fragments are preserved through URL normalisation. The cross-page link above compiles to ../api/cli-commands/#available-flags.
By default, docmd generates contextual (hierarchical) heading IDs that incorporate parent section names (e.g. ## Configuration under # Setup becomes #setup-configuration).
To match GitHub’s flat slug style for repositories shared with GitHub or external renderers, configure "markdown": { "headingIds": "github" } in docmd.config.json or add headingIds: github to page frontmatter. In GitHub mode, headings produce flat un-nested anchors (e.g. #configuration, and -- is preserved when punctuation like & is stripped).
Opening External Links in New Tabs
Prepend external: to any URL target to force the link to open in a new browser tab (target="_blank"):
[Open in New Tab](external:./configuration/overview.md)
[GitHub Repository](external:https://github.com/docmd-io/docmd)
The external: prefix string is stripped from rendered HTML href attributes.
Direct Unprocessed Asset Links (raw:)
Use the raw: prefix to bypass URL normalisation and target static downloadable files directly:
[Download Raw Source](raw:docs/readme.md)
Rich Containers & Interactive Elements
Button (::: button) and Tag (::: tag) containers support all linking prefixes, including external: and raw: modifiers:
::: button title:"Quick Start Guide" url:"./getting-started/quick-start.md" icon:rocket
::: button title:"GitHub Repository" url:"external:https://github.com/docmd-io/docmd" icon:github
::: button title:"Download Manifest" url:"raw:docs/manifest.json" icon:download
::: tag title:"v0.9.0 Release" link:release-notes/0-9-0.md icon:tag color:#22c55e
::: tag title:"External Site" link:external:https://docmd.io icon:external-link
Navigation Configuration Links
Route entries in navigation.json and docmd.config.json are normalised automatically during build compilation:
[
{ "title": "Overview", "path": "configuration/overview" },
{ "title": "Overview", "path": "configuration/overview.md" },
{ "title": "Overview", "path": "configuration/overview/" }
]
To force a navigation item to open in a new tab, set "external": true:
[
{
"title": "GitHub",
"path": "https://github.com/docmd-io/docmd",
"external": true
}
]
When linking to a subdirectory’s index page, reference the folder path directly (localisation/) rather than appending index.md.
Protocols & Asset Paths
The compiler preserves standard network protocols and static asset paths:
- HTTPS Protocols:
[docmd Homepage](https://docmd.io)(opens in same tab unlessexternal:is prefixed). - Mail Protocols:
[Support Desk](mailto:help@docmd.io)(triggers email client). - Static Assets:
[Download Asset](/assets/bin/docmd-mac.zip)(bypasses URL normalisation).
Use descriptive anchor text ([Configure PWA caching](../plugins/pwa.md)) instead of generic labels ([Read more](../plugins/pwa.md)). Explicit link text improves semantic understanding for search indexers and AI agents.