Package: mkdocs-alias-plugin
mkdocs-alias-pluginAn MkDocs plugin allowing links to your pages using a custom alias such as[[my-alias]]or[[my-alias|My Title]].The aliases are configured through the meta-sections of each page (see Usage below).If you like this plugin, you'll probably also likemkdocs-categories-pluginandmkdocs-live-edit-plugin.RationaleI maintain a fairly large wiki and occasionally will restructure parts of it, resulting in many broken links. This plugin allows me to separate the wiki contents from the file system structure and resolves the paths during build time. Maybe this plugin will help you out as well.InstallationInstall the package using pip:pipinstallmkdocs-alias-pluginThen add the following entry to the plugins section of yourmkdocs.ymlfile:plugins:
  - aliasFor further configuration, see the Options section below.UsageAdd analiassection 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.Or, a more advanced example by using the dictionary-style configuration instead to provide a different link title.---alias:name:wuthering-heightstext:Wuthering Heights, a novel by Emily Brontë---If you'd like to supply your own link text instead on a link-by-link basis, you can do so using a pipe to separate the title from the alias:The song references [[wuthering-heights|Wuthering Heights]].As of version 0.6.0, you can also use link anchors in your aliases:The song references [[wuthering-heights#references]].Or, also using a title:The song references [[wuthering-heights#references|Wuthering Heights]].Please refer to theMkDocs documentationfor more information on how the meta-data block is used.Multiple AliasesAs of version 0.3.0, it is possible to assign multiple aliases to a single page. This does come with the limitation that these aliases cannot define a per-alias title. The syntax for this is:---alias:-wuthering-heights-wuthering-wh---Escaping Aliases (Escape Syntax)As of version 0.4.0, it is possible to escape aliases to prevent them being parsed by the plugin. This is useful if you use a similar double-bracket markup for a different purpose (e.g. shell scripts). The syntax for this feature is a leading backslash:\[[this text will remain untouched]]

[[this text will be parsed as an alias]]OptionsYou may customize the plugin by passing options into the plugin's configuration sections inmkdocs.yml:plugins:-alias:verbose:trueverboseYou may use the optionalverboseoption to print more information about which aliases were used and defined during build. The default value isfalse.TroubleshootingThe link text looks like a path or URLYour alias doesn't have link text definedandyour page doesn't have a title H1 tag or atitleattribute in its meta data section. Once you add this, your link will render with the appropriate text.My alias is not being replacedWARNING  -  Alias 'my-alias' not foundThe 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.Aliasesmustbe unique. Ensure that you're not redefining the same alias for a different page. Rename one of them and the warning should go away.Local DevelopmentInstalling a local copy of the plugin:pipinstall-e/path/to/mkdocs-alias-plugin/Running unit tests after installing pytest from the root directory:pytest-vvBoth unit test and linting:pylint$(gitls-files'*.py')&&pytest-vvChangelog0.7.02024-02-01Removed support for theuse_relative_linkoption introduced in issue #3. As of 1.5.0, MkDocs prefers relative links to absolute links, which were the default of this package before. As of this version, all alias links generated are relative to the file they were linked from.0.6.02023-04-17Adds support for page anchor links from within an alias. E.g.:[[my alias#my anchor]]0.5.02023-02-08Adds the ability to use theuse_relative_linkconfig flag, which causes the plugin to generate relative links to the aliased document rather than absolute ones. This flag is useful for those who host their wikis in subdirectories.@SimonDelmas contributed this feature in PR #3. Thanks!0.4.02022-07-10Adds the ability to escape aliases so they won't be parsed by the plugin. Also adds more unit tests.0.3.02022-04-27Adds the ability to create multiple aliases for a single page (see the documentation for "Multiple Aliases" above). Improves the "alias not found" warning by listing the file attempting to use the alias.0.2.02022-02-23Allow strings as aliases instead of dictionaries, which allows for the use of page titles in the link text of the alias.This version also makes thetextkey optional in the alias dictionary configuration, using the same page title link text instead if it's not provided.0.1.12022-02-12Fixes a bunch of linter issues, but no new logic.0.1.02022-02-12Initial release with all of the base logic in place.