| Name | mkdocs-awesome-autolinks JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | An MkDocs plugin for linking without specifying the full relative path and other features that ease using the file structure to generate navigation. |
| upload_time | 2025-03-20 12:28:23 |
| maintainer | None |
| docs_url | None |
| author | Johan Boer |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
mkdocs
markdown
awesome
autolinks
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mkdocs-awesome-autolinks
The MkDocs Awesome Autolinks plugin makes it possible to link to pages and images without specifying the full path. For example if there is a page `project/general/overview.md` this plugin allows you to
link to the page from any other page with just using a part of the path like `[overview](overview.md)`
or `[overview](general/overview.md)`. This not only works for links to other pages but also to any
other type of file.
In addition to automatically resolving links this plugin complements the
[Awesome Nav][awesome-pages] plugin when [using a * glob pattern][glob-pattern] to automatically include pages in the menu.
Of course the order of menu entries is important, when pages are automatically included the sort
order determines the order in the menu. This can easily be influenced by prefixing a page name or
directory with a number for sorting. Unfortunately this also means that links will more easily break
because of file renaming.
This plugin can automatically remove a prefix from all parts of a link. For example if there is a page `010-project/200-general/999-overview.md` this plugin allows you to
link to the page with `[overview](overview.md)`, `[overview](general/overview.md)` or
`[overview](project/general/overview.md)`. Breaking links because of renaming a file to change the
sort order will no longer be an issue.
The functionality to remove a part of file and directory names can be disabled in `mkdocs.yml` and
the autolink functionality will continue to work.
[awesome-pages]: https://github.com/lukasgeiter/mkdocs-awesome-nav
[glob-pattern]: https://lukasgeiter.github.io/mkdocs-awesome-nav/features/nav/#glob-patterns
## Installation
> **Note:** This package requires Python >=3.7 and MkDocs version 1.4 or higher.
Install the package with pip:
```bash
pip install mkdocs-awesome-autolinks
```
Enable the plugin in your `mkdocs.yml`:
```yaml
plugins:
- awesome-autolinks
```
Configuration of the plugin is possible but not necessary if the default behavior suits your need.
## Usage
More information will be provided in the future. Here is a short summary of how the
automatic linking can be used.
* The default prefix that is automatically removed from all parts of a link has the following pattern:
One or more numbers followed by a `-`. For example `010-about.md` or
in case of a file in a directory `100-examples/010-about.md` will be replaced with `about.md`
and `examples/about.md`.<br>
You can define your own pattern in the config. Removal of a prefix can be disabled by setting
`remove_re` to an empty string.
* Instead of specifying the entire relative path in a link, include only the part of the destination that you are certain will remain unique. From here on
it will be called a *short link*.<br>
This plugin will replace a short link with the relative path to the page file it points to.
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
that match the path of that short link a warning will be logged. If configuration setting `warn_less`
is true, a warning is not logged if there is a single destination in the same directory branch of the page that contains the short link.
So it is ok to have a link `[About](about.md)` on a page if file `about.md` is located somewhere in
a subdirectory of the directory where the page with the short link is located. Even if there are
other `about.md` files in other directory branches, as long as they can only be reached by going
higher up in the directory tree (do a ../ first).
## Configuration
The following configuration options can be set in `mkdocs.yml`. Values shown here are the default.
``` yaml
plugins:
- awesome-autolinks:
remove_re: '^[0-9]+-'
warn_less: false
warn_on_no_use: true
ignore_dirs:
- css
- fonts
- img
- js
- search
- javascripts
- assets/javascripts
debug: false
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-awesome-autolinks",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mkdocs, markdown, awesome, autolinks",
"author": "Johan Boer",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/29/67/cd854c2e493f9d7123a1eccd610ad98c0c42e930023953b24503b03a89c7/mkdocs_awesome_autolinks-1.0.0.tar.gz",
"platform": null,
"description": "# mkdocs-awesome-autolinks\n\nThe MkDocs Awesome Autolinks plugin makes it possible to link to pages and images without specifying the full path. For example if there is a page `project/general/overview.md` this plugin allows you to\nlink to the page from any other page with just using a part of the path like `[overview](overview.md)`\nor `[overview](general/overview.md)`. This not only works for links to other pages but also to any\nother type of file.\n\nIn addition to automatically resolving links this plugin complements the \n[Awesome Nav][awesome-pages] plugin when [using a * glob pattern][glob-pattern] to automatically include pages in the menu. \nOf course the order of menu entries is important, when pages are automatically included the sort\norder determines the order in the menu. This can easily be influenced by prefixing a page name or\ndirectory with a number for sorting. Unfortunately this also means that links will more easily break\nbecause of file renaming.\n\nThis plugin can automatically remove a prefix from all parts of a link. For example if there is a page `010-project/200-general/999-overview.md` this plugin allows you to\nlink to the page with `[overview](overview.md)`, `[overview](general/overview.md)` or \n`[overview](project/general/overview.md)`. Breaking links because of renaming a file to change the\nsort order will no longer be an issue.\n\nThe functionality to remove a part of file and directory names can be disabled in `mkdocs.yml` and\nthe autolink functionality will continue to work.\n\n[awesome-pages]: https://github.com/lukasgeiter/mkdocs-awesome-nav\n[glob-pattern]: https://lukasgeiter.github.io/mkdocs-awesome-nav/features/nav/#glob-patterns\n\n## Installation\n\n> **Note:** This package requires Python >=3.7 and MkDocs version 1.4 or higher. \n\nInstall the package with pip:\n\n```bash\npip install mkdocs-awesome-autolinks\n```\n\nEnable the plugin in your `mkdocs.yml`:\n\n```yaml\nplugins:\n - awesome-autolinks\n```\n\nConfiguration of the plugin is possible but not necessary if the default behavior suits your need.\n\n## Usage\nMore information will be provided in the future. Here is a short summary of how the\nautomatic linking can be used.\n\n* The default prefix that is automatically removed from all parts of a link has the following pattern:\nOne or more numbers followed by a `-`. For example `010-about.md` or\nin case of a file in a directory `100-examples/010-about.md` will be replaced with `about.md`\nand `examples/about.md`.<br>\nYou can define your own pattern in the config. Removal of a prefix can be disabled by setting\n`remove_re` to an empty string.\n\n* Instead of specifying the entire relative path in a link, include only the part of the destination that you are certain will remain unique. From here on\nit will be called a *short link*.<br>\nThis plugin will replace a short link with the relative path to the page file it points to.\nNormal MkDocs processing will transform the Markdown link with relative path to HTML.\n\n* In case there is a short link on a page but there are multiple files in the whole docs directory\nthat match the path of that short link a warning will be logged. If configuration setting `warn_less`\nis true, a warning is not logged if there is a single destination in the same directory branch of the page that contains the short link.\n\n So it is ok to have a link `[About](about.md)` on a page if file `about.md` is located somewhere in\na subdirectory of the directory where the page with the short link is located. Even if there are\nother `about.md` files in other directory branches, as long as they can only be reached by going\nhigher up in the directory tree (do a ../ first).\n\n\n## Configuration\n\nThe following configuration options can be set in `mkdocs.yml`. Values shown here are the default.\n\n``` yaml\nplugins:\n - awesome-autolinks:\n remove_re: '^[0-9]+-'\n warn_less: false\n warn_on_no_use: true\n ignore_dirs:\n - css\n - fonts\n - img\n - js\n - search\n - javascripts\n - assets/javascripts\n debug: false\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An MkDocs plugin for linking without specifying the full relative path and other features that ease using the file structure to generate navigation.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/Johan-EU/mkdocs-awesome-autolinks"
},
"split_keywords": [
"mkdocs",
" markdown",
" awesome",
" autolinks"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6df221be45a05df4b9f7921392da9db851ed989bccd3a0094358510f56af2530",
"md5": "b1784dade51152bf77fde95ce18fb914",
"sha256": "effd82f313100a0e3bb1d7afee27cff3c70eed7e5546d63c2b9f32f1bf6d69b9"
},
"downloads": -1,
"filename": "mkdocs_awesome_autolinks-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b1784dade51152bf77fde95ce18fb914",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7475,
"upload_time": "2025-03-20T12:28:22",
"upload_time_iso_8601": "2025-03-20T12:28:22.487041Z",
"url": "https://files.pythonhosted.org/packages/6d/f2/21be45a05df4b9f7921392da9db851ed989bccd3a0094358510f56af2530/mkdocs_awesome_autolinks-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2967cd854c2e493f9d7123a1eccd610ad98c0c42e930023953b24503b03a89c7",
"md5": "4f3e92e2de8273da214d81ed69cde1c4",
"sha256": "4e7437822cdaacf1a6b501d2a4c5cb30c7e9a7950892fecf4d59342bd76ccbfc"
},
"downloads": -1,
"filename": "mkdocs_awesome_autolinks-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "4f3e92e2de8273da214d81ed69cde1c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7407,
"upload_time": "2025-03-20T12:28:23",
"upload_time_iso_8601": "2025-03-20T12:28:23.649376Z",
"url": "https://files.pythonhosted.org/packages/29/67/cd854c2e493f9d7123a1eccd610ad98c0c42e930023953b24503b03a89c7/mkdocs_awesome_autolinks-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-20 12:28:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Johan-EU",
"github_project": "mkdocs-awesome-autolinks",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-awesome-autolinks"
}
