Package: mkdocs-awesome-autolinks
mkdocs-awesome-autolinksThe MkDocs Awesome Autolinks plugin makes it possible to link to pages and images without specifying the full relative path. In addition, to ease using the file structure to generate navigation, it will remove a configurable part from the directory and page file name that can be used to order the navigation and page structure.As a result the part of directory and page names that is used to order pages does not have to be included in links and will not show in the URLs of the built site. Otherwise links would break when the page order is changed and the part used for sorting would clutter the site URLs.This plugin has been built to be used in combination with theAwesome Pages pluginthat allowscombination of custom navigation with file
structure. Hence the awesome in the name of this plugin.
Tough there is no relation with or dependency on the Awesome Pages Plugin.The functionality to remove a part of file and directory names can be disabled inmkdocs.ymland
the autolink functionality will continue to work.InstallationNote:This package requires Python >=3.7 and MkDocs version 1.4 or higher.Install the package with pip:pipinstallmkdocs-awesome-autolinksEnable the plugin in yourmkdocs.yml:plugins:-awesome-autolinksConfiguration of the plugin is possible but not necessary if the default behavior suits your need.UsageMore information will be provided in the future. Here is a short summary of how the
automatic linking can be used.The default pattern for the sorting part of directory and file names is that the start
of each file/directory name contains numbers followed by a-. For example010-about.mdor
in case of a file in a directory100-examples/010-about.md.There is no limit to the amount of numbers.Instead of specifying the full relative path in a link only include the file name. From here on
it will be called ashort link. An example of a short link is[About](about.md). This plugin will replaceabout.mdwith the relative path to the page file.
Normal MkDocs processing will transform the Markdown link with relative path to HTML.In case there is a short link on a page but there are multiple files in the whole docs directory
with the file name of that short link a warning will be logged but this depends of thewarn_lesssetting. Ifwarn_lessis true, the default, a warning is only logged if there is no file with the
same name in the same directory branch or if there are multiple files with the same name in the same
directory branch.So it is safe to have link[About](about.md)on a page if fileabout.mdis located somewhere in
a subdirectory of the directory where the page with the short link is located. Even if there are
otherabout.mdfiles in other directory branches, as long as they can only be reached by going
higher up in the directory tree (do a ../ first).Some page file names are very common. Instead of forcing unique file names the directory
the file is located in can be included in the short link. For example[Subject A](subject-a/index.md).Normal relative links such as[Subject A](../subjects/subject-a/index.md)can still be used.
Configuration settingwarn_on_no_usewill determine whether a warning will be logged about not
using the autolink functionality.Removal of a part from the directory and page file names can be disabled by settingremove_reto an empty string.ConfigurationThe following configuration options can be set inmkdocs.yml. Values shown here are the default.plugins:-awesome-autolinks:remove_re:'^[0-9]+-'warn_less:truewarn_on_no_use:trueignore_dirs:-css-fonts-img-js-searchdebug:false