MkDocs Alias Plugin
The mkdocs-alias-plugin MkDocs plugin allows links to your pages using custom aliases:
This is a link to [[my-page]].
This is a link to [[my-page|the same]] alias.
Using aliases allows you to decouple the file structure of your MkDocs wiki from its taxonomy. For example, if you have a wiki about animals which accidentally classifies pigs as reptiles, after moving the file into the mammals directory, you won’t have to update all of the links to the pig page. Depending on the size of your wiki, this can save quite a bit of time.
This plugin uses a wikilinks-like syntax, but is different in that the aliases are configured through the frontmatter (meta-sections) of each page, rather than defined by the page’s titles. For example, adding the following item to your page’s frontmatter allows you to use the above alias:
alias: my-page
This is the most common use case. If you have more advanced needs, you can find more complex examples in the Usage section below.
Table of Contents
Installation
Install the package using pip:
pip install mkdocs-alias-plugin
Then add the following entry to the plugins section of your mkdocs.yml file:
plugins:
- alias
For further configuration, see the Options section below.
Usage
This section lists the plugin’s features, together with the minimum version number of the plugin required to use the feature. The current version of the plugin is: 
Unless you have a good reason to do so, you should always use the latest version of this plugin. If you do have a good reason, please file a bug!
If you have a use case that you think may be useful in a general context, please feel free to file a feature request.
Common
Minimum Version: 0.2.0
Add an alias section to your page’s meta block:
alias: wuthering-heights
Then, using the alias in the markdown content of your pages:
The song references [[wuthering-heights]].
Which, after the page builds, renders as a regular link to your page.
Pre-Defined Titles
Minimum Version: 0.1.0
A more advanced example would be to use the dictionary-style configuration instead of providing a different link title:
alias:
name: wuthering-heights
text: Wuthering Heights, a novel by Emily Brontë
Multiple Aliases
Minimum Version: 0.3.0
It’s possible to define multiple aliases per wiki page using the YAML array syntax instead:
alias:
- wuthering-heights
- wuthering
- wh
Note: This feature does come with the limitation that these aliases cannot define a per-alias title and instead will use the page title.
Inline Titles
Minimum Version: 0.1.0
If you’d like to supply a custom link text instead on a link-by-link basis, you can do so using a pipe to separate the title from the alias:
[[wuthering-heights|Wuthering Heights]].
Linking Anchors
Minimum Version: 0.6.0
You may also link to anchors on the page defining the alias:
[[wuthering-heights#references]].
Or, using a custom title:
[[wuthering-heights#references|Wuthering Heights]].
Automatic Anchor Titles
Minimum Version: 0.8.0
You can enable the plugin option use_anchor_titles to replace anchor links with the text of the page heading that defined it. This behavior is opt-in to preserve backward compatibility. For example, the page defininig the alias:
---
alias: wh
---
# Wuthering Heights
Lorem ipsum.
## Popular Media
Dolor sit amet.
On the linking page:
Wuthering Heights in [[wh#popular-media]].
Renders the link’s text as “Wuthering Heights in Popular Media.”
Escape Syntax
Minimum Version: 0.4.0
It is possible to escape aliases to prevent them from being parsed by the plugin. This is useful if you use a similar double-bracket markup for a different purpose (e.g. shell scripts in code blocks). The syntax for this feature is a leading backslash:
# The escaped version will render correctly, without the backslash.
\[[ $STRING != foo ]]
# The unescaped version will be treated as an alias!
[[ $STRING != foo ]]
Footnote Syntax
Minimum Version: 0.10.0
It’s possible to use a specialized version of the alias syntax for aliases in footnotes:
The song references [Wuthering Heights][wuthering-heights].
[wuthering-heights]: [[wuthering-heights#references]]
Since this formats footnote-style links using a different syntax than valid Markdown, your linter may object and automatically remove the links upon saving. To get around this for markdownlint, disable rule MD053 in your .markdownlint.json file.
Interwiki Links
Minimum Version: 0.11.0
You may use a specialized version of the alias syntax to link to external sources defined in your alias plugin options. See the interwiki section for more details on how to set this up:
[[w:Hypertext]]
Or, defining a custom title:
[[[w:Hypertext|The Wikipedia Article on Hypertext]]]
Including anchors in the link is also allowed.
Using aliases
Minimum Version: 0.9.0
You may also use the key aliases in addition to (or in place of) the alias key in the meta section of your pages. This is to provide some similarity to other Markdown-based software that supports aliases, such as Obsidian.
Options
The plugin’s default configuration may be overridden by passing options into the plugin’s configuration sections in mkdocs.yml:
plugins:
- alias:
verbose: true
use_anchor_titles: true
use_page_icon: true
interwiki:
wp: https://en.wikipedia.org/wiki/{{alias}}
verbose
Minimum Version: 0.1.0
Default Value: false
You may use the optional verbose option to print more information about which aliases were used and defined during the build process. A tab-delimited file named aliases.log will also be defined at the project root, containing a list of every alias defined by the wiki.
The default value is false and should only be enabled when debugging issue with the plugin.
use_anchor_titles
Minimum Version: 0.8.0
Default Value: false
Setting this flag to true causes the plugin to replace an alias containing an anchor ([[my-page#sub-heading]]) with the text of the header that defined it. You can still override the title of the link as usual.
use_page_icon
Minimum Version: 0.9.0
Default Value: false
Setting this flag to true will include the page’s icon in the alias substitution if it’s set for a given page.
interwiki
Minimum Version: 0.11.0
Default Value: None
This is defined as a dictionary strings mapped to URL templates, e.g.:
interwiki:
wp: 'https://en.wikipedia.org/wiki/{{alias}}'
k: 'https://kagi.com/search?q={{alias}}'
Where the string {{alias}} is replaced with value from the alias. See the Interwiki Links section above on how to use these in tags.
Troubleshooting
The link text looks like a path or URL
Your alias doesn’t have link text defined and your page doesn’t have a title H1 tag or a title attribute in its meta data section. Once you add this, your link will render with the appropriate text.
My alias is not replaced
WARNING - Alias 'my-alias' not found
The alias could not be found in the defined aliases, usually due to a typo. Enable verbose output in the plugin’s configuration to display all of the found aliases.
However, it is also possible that the plugin is trying to interpret another double-bracketed syntax as an alias. In this case, use the escape syntax to prevent the plugin from parsing it.
“Alias already defined”
You’re getting a message resembling this in your output:
WARNING - page-url: alias alias-name already defined in other-url, skipping.
Aliases must be unique. Ensure that you’re not redefining the same alias for a different page. Rename one of them and the warning will go away.
Aliases with alternative titles break $my_markdown_tool
This is a limitation of extending the Markdown syntax with non-standard features, which this MkDocs plugin does. Within Markdown tables, rather than using the standard alias links ([[the-alias|The Title]]), I recommend you use footnote-style aliases instead to prevent breaking formatters and tools unaware of this plugin’s existence. See issue #24 for more context.
Footnote links disappear when I save my file
Since markdownlint isn’t aware of alias-style links, the links are considered “unused” by the linter. To get around this, disable rule “MD053” in your .markdownlint.json file.
How do I use square brackets in an alias?
To use square brackets in the custom substitution text of an alias, you can escape them with a backslash (\). For example:
[[the-alias|The \[bracketed\] Title]]
Contributing
If you find a bug, a typo or omission in the documentation, or wish to contribute to the plugin itself, please head on over to the plugin’s Codeberg repository for more instructions.