Package: mkdocs-addresses
LinksProject repository (GitLab)Full online documentationThe project on PyPIDependenciesPython 3.8+mkdocs 1.4+BeautifulSoup 4+OverviewAboutThemkdocs-addressesis a plugin formkdocswhich offers:Abstraction of the concrete tree hierarchy of pages and anchors within those when writing a link, utilizing unique identifiers:Benefit from a strong separation between logic and content, avoiding all addresses rewrite steps when some files are modified, split, merged or moved.Verification of numerous links and addresses to ensure the absence of dead links or images within the documentation (including verifications beyond mkdocs 1.5+ capabilities):The tool warns you when something becomes wrong during development.Convenient helpers to facilitate the usage of those identifiers within the docs pages. For users working with compatible IDEs, this translates to the availability of auto-completion features:Don't lose time searching for the exact name of the anchor in the file that is... where is it again? Let the autocompletion tool find them for you.Identifiers: separating structure from contentRelying on theattr_listmarkdown extension, use identifiers instead of actual paths to point to specific anchors in the documentation:## Very important title with anchor and id {: #point-here }In another file: navigate to [this very important title](--point-here).The plugin automatically rebuilds the appropriate addresses, considering various factors such as the source file  location, the target, theuse_directory_urlsoption, ...Reduce dependencies on the files hierarchyIdentifiers still work after:Changing header contentMoving sections from one file to anotherRenaming filesMoving filesProvideautocompletion helpers(IDE dependent)(Currently only available for VSC-like IDEs)All snippets are automatically kept up to date while working on the documentation.They provide various markdown snippets, to get a quick and easy access to all the references defined in the documentation, and use them within the markdown code they are usual used for.KindSuggestion completionInserted markdownDoc identifier--point-here--point-hereDoc linksLink.point-here[link to some place in the docs](--point-here)Images inassets/(identifier)!!file_in_assets_jpg!!file_in_assets_jpgImages inassets/Img.file_in_assets_jpg![alt content](!!file_in_assets_jpg)Other files links++file_path_in_docs_html++file_path_in_docs_htmlOther files linksFile.file_path_in_docs_html[link to a file](++file_path_in_docs_html)External Links*Ext.global_ref[global_ref][global_ref]Code inclusions**::md that_file_md--<8-- "include/that_file.md"*: requires anexternal_links_filefor global references is configured.**: requires the use ofinclusionsdirectories.Tracking dead links or addresses in the docsThe plugin also explores the documentation and warns you if it finds invalid addresses or identifiers. This works for:Addresses in linksAddresses of imagesIdentifiers used by the pluginUser handed configurationA lot ofoptionsare available for the user to fine tune the plugin's behavior.InstallationInstall the package on your machine (or in your project if you are using a virtual env):pip install mkdocs-addressesRegister the plugin in themkdocs.ymlfile:plugins:-search# To redeclare when plugins are added to mkdocs.yml-mkdocs-addressesConfigure the plugin (see below).Recommendedmkdocs.ymlconfigurationSee theonline documentationfor more details.Markdown extensionsmarkdown_extensions:-attr_list# To define the identifiers in the markdown content-pymdownx.snippets:# If you need inclusions code snippetscheck_paths:trueauto_append:["path_to_external_links_definition.md"]#               ^ see plugin's external_link_file configurationPlugin configurationplugins:-search-mkdocs-addresses:-external_links_file:path_to_links_definition_if_any.md-inclusions:-location1_if_any-location2...Note that the default configuration also implies the following choices:-dump_snippets_file:.vscode/links.code-snippets-fail_fast:false-ignore_auto_headers:true-use_vsc:trueSo, if VSC isn't the utilized IDE, theuse_vscoption should at the very least be modified.When using mkdocs 1.5+Significant enhancements in address verification logic (which was notoriously lacking in earlier versions...) have been added inmkdocs 1.5+. But the plugin does more work, and the identifiers it is utilizing are generating warnings in the console.Hence, deactivate the default verification logic for mkdocs 1.5+:validation:absolute_links:ignoreunrecognized_links:ignoreLinksProject repository (GitLab)Full online documentationThe project on PyPILicenseApache-2.0Copyright © 2023 Zinelli Frédéric