 
## Links
* [Project repository (GitLab)](https://gitlab.com/frederic-zinelli/mkdocs-addresses)
* [Full online documentation](http://frederic-zinelli.gitlab.io/mkdocs-addresses/)
* [The project on PyPI](https://pypi.org/project/mkdocs-addresses/)
## Dependencies
* Python 3.8+
* mkdocs 1.4+
* BeautifulSoup 4+
## Overview
### About
The [`mkdocs-addresses`](https://pypi.org/project/mkdocs-addresses/) is a plugin for `mkdocs` which 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.
<br>
* 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.
<br>
* 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.
<br>
### Identifiers: separating structure from content
Relying on the `attr_list` markdown extension, use identifiers instead of actual paths to point to specific anchors in the documentation:
```code
## Very important title with anchor and id {: #point-here }
```
```code
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, the `use_directory_urls` option, ...
### Reduce dependencies on the files hierarchy
Identifiers still work after:
- Changing header content
- Moving sections from one file to another
- Renaming files
- Moving files
### Provide [autocompletion helpers](http://frederic-zinelli.gitlab.io/mkdocs-addresses/autocompletion/) (_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.
| Kind | Suggestion completion | Inserted markdown |
|:-|:-|:-|
| Doc identifier | `--point-here` | `--point-here` |
| Doc links | `Link.point-here` | `[link to some place in the docs](--point-here)` |
| Images in `assets/` (identifier) | `!!file_in_assets_jpg` | `!!file_in_assets_jpg` |
| Images in `assets/` | `Img.file_in_assets_jpg` | `` |
| Other files links | `++file_path_in_docs_html` | `++file_path_in_docs_html` |
| Other files links | `File.file_path_in_docs_html` | `[link to a file](++file_path_in_docs_html)` |
| External Links <sup>\*</sup> | `Ext.global_ref` | `[global_ref][global_ref]` |
| Code inclusions<sup>\*\*</sup> | `::md that_file_md` | `--<8-- "include/that_file.md"` |
\*: requires an [external_links_file](http://frederic-zinelli.gitlab.io/mkdocs-addresses/configuration/#mkdocs_addresses.config_plugin.PluginOptions.external_links_file) for global references is configured.
\*\*: requires the use of [inclusions](http://frederic-zinelli.gitlab.io/mkdocs-addresses/configuration/#mkdocs_addresses.config_plugin.PluginOptions.inclusions) directories.
### Tracking dead links or addresses in the docs
The plugin also explores the documentation and warns you if it finds invalid addresses or identifiers. This works for:
- Addresses in links
- Addresses of images
- Identifiers used by the plugin
### User handed configuration
A lot of [options](http://frederic-zinelli.gitlab.io/mkdocs-addresses/configuration/) are available for the user to fine tune the plugin's behavior.
## Installation
Install the package on your machine (or in your project if you are using a virtual env):
```
pip install mkdocs-addresses
```
Register the plugin in the `mkdocs.yml` file:
```yaml
plugins:
- search # To redeclare when plugins are added to mkdocs.yml
- mkdocs-addresses
```
Configure the plugin (see below).
### Recommended `mkdocs.yml` configuration
See the [online documentation](http://frederic-zinelli.gitlab.io/mkdocs-addresses/#installation) for more details.
#### Markdown extensions
```yaml
markdown_extensions:
- attr_list # To define the identifiers in the markdown content
- pymdownx.snippets: # If you need inclusions code snippets
check_paths: true
auto_append: ["path_to_external_links_definition.md"]
# ^ see plugin's external_link_file configuration
```
#### Plugin configuration
```yaml
plugins:
- 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:
```yaml
- dump_snippets_file: .vscode/links.code-snippets
- fail_fast: false
- ignore_auto_headers: true
- ide: vsc
```
So, if VSC isn't the utilized IDE, the [`ide`](http://frederic-zinelli.gitlab.io/mkdocs-addresses/configuration/#mkdocs_addresses.config_plugin.PluginOptions.ide) option 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 in `mkdocs 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+:
```yaml
validation:
absolute_links: ignore
unrecognized_links: ignore
```
## Links
* [Project repository (GitLab)](https://gitlab.com/frederic-zinelli/mkdocs-addresses)
* [Full online documentation](http://frederic-zinelli.gitlab.io/mkdocs-addresses/)
* [The project on PyPI](https://pypi.org/project/mkdocs-addresses/)
## License
[Apache-2.0](https://www.tldrlegal.com/license/apache-license-2-0-apache-2-0)
Copyright © 2023 Zinelli Frédéric
Raw data
{
"_id": null,
"home_page": "http://frederic-zinelli.gitlab.io/mkdocs-addresses/",
"name": "mkdocs-addresses",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "mkdocs, mkdocs-plugin, links, autocompletion",
"author": "Fr\u00e9d\u00e9ric Zinelli",
"author_email": "frederic.zinelli@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ab/90/0a1c73f479fd979b7ce018cc328d1b1518094388ff5a94a6c39176256c44/mkdocs_addresses-0.3.1.tar.gz",
"platform": null,
"description": "\n \n\n\n## Links\n\n* [Project repository (GitLab)](https://gitlab.com/frederic-zinelli/mkdocs-addresses)\n* [Full online documentation](http://frederic-zinelli.gitlab.io/mkdocs-addresses/)\n* [The project on PyPI](https://pypi.org/project/mkdocs-addresses/)\n\n\n\n## Dependencies\n\n* Python 3.8+\n* mkdocs 1.4+\n* BeautifulSoup 4+\n\n\n\n## Overview\n\n### About\n\nThe [`mkdocs-addresses`](https://pypi.org/project/mkdocs-addresses/) is a plugin for `mkdocs` which offers:\n\n* Abstraction of the concrete tree hierarchy of pages and anchors within those when writing a link, utilizing unique identifiers:\n\n Benefit from a strong separation between logic and content, avoiding all addresses rewrite steps when some files are modified, split, merged or moved.\n <br>\n\n* 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):\n\n The tool warns you when something becomes wrong during development.\n <br>\n\n* 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:\n\n 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.\n <br>\n\n\n\n### Identifiers: separating structure from content\n\nRelying on the `attr_list` markdown extension, use identifiers instead of actual paths to point to specific anchors in the documentation:\n\n```code\n## Very important title with anchor and id {: #point-here }\n```\n\n```code\nIn another file: navigate to [this very important title](--point-here).\n```\n\nThe plugin automatically rebuilds the appropriate addresses, considering various factors such as the source file location, the target, the `use_directory_urls` option, ...\n\n\n### Reduce dependencies on the files hierarchy\n\nIdentifiers still work after:\n- Changing header content\n- Moving sections from one file to another\n- Renaming files\n- Moving files\n\n\n\n\n### Provide [autocompletion helpers](http://frederic-zinelli.gitlab.io/mkdocs-addresses/autocompletion/) (_IDE dependent_)\n\n_(Currently only available for VSC-like IDEs)_\n\n* All snippets are automatically kept up to date while working on the documentation.\n* 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.\n\n| Kind | Suggestion completion | Inserted markdown |\n|:-|:-|:-|\n| Doc identifier | `--point-here` | `--point-here` |\n| Doc links | `Link.point-here` | `[link to some place in the docs](--point-here)` |\n| Images in `assets/` (identifier) | `!!file_in_assets_jpg` | `!!file_in_assets_jpg` |\n| Images in `assets/` | `Img.file_in_assets_jpg` | `` |\n| Other files links | `++file_path_in_docs_html` | `++file_path_in_docs_html` |\n| Other files links | `File.file_path_in_docs_html` | `[link to a file](++file_path_in_docs_html)` |\n| External Links <sup>\\*</sup> | `Ext.global_ref` | `[global_ref][global_ref]` |\n| Code inclusions<sup>\\*\\*</sup> | `::md that_file_md` | `--<8-- \"include/that_file.md\"` |\n\n\n\\*: requires an [external_links_file](http://frederic-zinelli.gitlab.io/mkdocs-addresses/configuration/#mkdocs_addresses.config_plugin.PluginOptions.external_links_file) for global references is configured.\n\n\\*\\*: requires the use of [inclusions](http://frederic-zinelli.gitlab.io/mkdocs-addresses/configuration/#mkdocs_addresses.config_plugin.PluginOptions.inclusions) directories.\n\n\n\n\n\n\n### Tracking dead links or addresses in the docs\n\nThe plugin also explores the documentation and warns you if it finds invalid addresses or identifiers. This works for:\n\n- Addresses in links\n- Addresses of images\n- Identifiers used by the plugin\n\n\n\n\n### User handed configuration\n\nA lot of [options](http://frederic-zinelli.gitlab.io/mkdocs-addresses/configuration/) are available for the user to fine tune the plugin's behavior.\n\n\n\n\n\n## Installation\n\nInstall the package on your machine (or in your project if you are using a virtual env):\n\n```\npip install mkdocs-addresses\n```\n\nRegister the plugin in the `mkdocs.yml` file:\n\n```yaml\nplugins:\n - search # To redeclare when plugins are added to mkdocs.yml\n - mkdocs-addresses\n```\n\nConfigure the plugin (see below).\n\n\n\n\n### Recommended `mkdocs.yml` configuration\n\nSee the [online documentation](http://frederic-zinelli.gitlab.io/mkdocs-addresses/#installation) for more details.\n\n#### Markdown extensions\n\n```yaml\nmarkdown_extensions:\n - attr_list # To define the identifiers in the markdown content\n - pymdownx.snippets: # If you need inclusions code snippets\n check_paths: true\n auto_append: [\"path_to_external_links_definition.md\"]\n # ^ see plugin's external_link_file configuration\n```\n\n#### Plugin configuration\n\n```yaml\nplugins:\n - search\n - mkdocs-addresses:\n - external_links_file: path_to_links_definition_if_any.md\n - inclusions:\n - location1_if_any\n - location2...\n```\n\nNote that the default configuration also implies the following choices:\n\n```yaml\n - dump_snippets_file: .vscode/links.code-snippets\n - fail_fast: false\n - ignore_auto_headers: true\n - ide: vsc\n```\nSo, if VSC isn't the utilized IDE, the [`ide`](http://frederic-zinelli.gitlab.io/mkdocs-addresses/configuration/#mkdocs_addresses.config_plugin.PluginOptions.ide) option should at the very least be modified.\n\n\n#### When using mkdocs 1.5+\n\nSignificant enhancements in address verification logic (which was notoriously lacking in earlier versions...) have been added in `mkdocs 1.5+`. But the plugin does more work, and the identifiers it is utilizing are generating warnings in the console.\n\nHence, deactivate the default verification logic for mkdocs 1.5+:\n\n```yaml\nvalidation:\n absolute_links: ignore\n unrecognized_links: ignore\n```\n\n\n## Links\n\n* [Project repository (GitLab)](https://gitlab.com/frederic-zinelli/mkdocs-addresses)\n* [Full online documentation](http://frederic-zinelli.gitlab.io/mkdocs-addresses/)\n* [The project on PyPI](https://pypi.org/project/mkdocs-addresses/)\n\n\n## License\n\n[Apache-2.0](https://www.tldrlegal.com/license/apache-license-2-0-apache-2-0)\nCopyright \u00a9 2023 Zinelli Fr\u00e9d\u00e9ric",
"bugtrack_url": null,
"license": null,
"summary": "Mkdocs automatic paths/addresses building - auto-completion support (VSC)",
"version": "0.3.1",
"project_urls": {
"Homepage": "http://frederic-zinelli.gitlab.io/mkdocs-addresses/",
"Repository": "https://gitlab.com/frederic-zinelli/mkdocs-addresses"
},
"split_keywords": [
"mkdocs",
" mkdocs-plugin",
" links",
" autocompletion"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d7154340199a68b36ce8a46ba0e882b0741eb2b2c837e29bd88985d508b95e16",
"md5": "37bd946592999d9c73cebd2656b337c6",
"sha256": "46c5e3f515b7d68c60c0039efdcf4af0814f04327826cdf420b00ead591a5028"
},
"downloads": -1,
"filename": "mkdocs_addresses-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37bd946592999d9c73cebd2656b337c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 115688,
"upload_time": "2024-04-08T15:18:01",
"upload_time_iso_8601": "2024-04-08T15:18:01.045171Z",
"url": "https://files.pythonhosted.org/packages/d7/15/4340199a68b36ce8a46ba0e882b0741eb2b2c837e29bd88985d508b95e16/mkdocs_addresses-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ab900a1c73f479fd979b7ce018cc328d1b1518094388ff5a94a6c39176256c44",
"md5": "12b5aa8017c700450c6edc99654a3199",
"sha256": "923c90fd9017eea1b2b36cf5017764acda73358a3c25268b913cb8abbd1c516f"
},
"downloads": -1,
"filename": "mkdocs_addresses-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "12b5aa8017c700450c6edc99654a3199",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 106176,
"upload_time": "2024-04-08T15:18:02",
"upload_time_iso_8601": "2024-04-08T15:18:02.817634Z",
"url": "https://files.pythonhosted.org/packages/ab/90/0a1c73f479fd979b7ce018cc328d1b1518094388ff5a94a6c39176256c44/mkdocs_addresses-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-08 15:18:02",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "frederic-zinelli",
"gitlab_project": "mkdocs-addresses",
"lcname": "mkdocs-addresses"
}
JSON