# mkdocs-backlinks
This is a plugin for adding backlinks to your mkdocs generated pages.
Mkdocs is an awesome tool not only for documentation, but also for publishing [digital gardens](https://danodic.dev).
Backlinks are a desirable component when building such digital gardens, as they enable the ability to explore content
based on how the knowledge interconnects instead of just looking at page navigation.
## Setup
Install the plugin using pip:
`pip install mkdocs-backlinks`
Activate the plugin in `mkdocs.yml`:
```yaml
plugins:
- mkdocs-backlinks
```
> **Note:** If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin.
> MkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.
More information about plugins in the [MkDocs documentation][mkdocs-plugins].
## Config
* `ignored_pages` - A list of page titles that will be excluded from the backlinks.
```yaml
plugins:
- mkdocs-backlinks:
ignored_pages: [ 'Tags', 'Home' ]
```
## Usage
This plugin will add a `backlinks` attribute to the Jinja page context, which can be used to add backlinks at any point
in your template. Here is an example of it:
```html
...
{% if backlinks %}
<h3>Backlinks:</h3>
<ul>
{% for backlink in backlinks %}
<li><a href="/{{ backlink.url }}">{{ backlink.title }}</a></li>
{% endfor %}
</ul>
{% endif %}
...
```
That means **you need to have a template that supports backlinks**, or you can alter the template you are using with the
snippet above.
### Writing Notes
I have been using this to publish my Obsidian vault, and there are some _tricks_ to make it work well:
- Obsidian is smart and will resolve links even if they don´t refer to a valid file path. This is not
true for mkdocs and the backlinks plugin -- you need to write valid links in your markdown files, either
absolute or relative links.
- Absolute links are absolute related to the root of the `/docs` folder, not to your computer filesystem.
Following those two rules will allow you to go straight from obsidian to mkdocs with cool backlinks.
## See Also
More information about templates [here][mkdocs-template].
More information about blocks [here][mkdocs-block].
[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/
[mkdocs-template]: https://www.mkdocs.org/user-guide/custom-themes/#template-variables
[mkdocs-block]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
## Thanks to
- The creator of this awsome mkdocs plugin template: https://github.com/byrnereese/mkdocs-plugin-template
Raw data
{
"_id": null,
"home_page": "https://github.com/danodic-dev/mkdocs-backlinks",
"name": "mkdocs-backlinks",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "mkdocs",
"author": "Danilo Guimar\u00e3es",
"author_email": "danilo@danodic.dev",
"download_url": "https://files.pythonhosted.org/packages/c4/d9/76b85008dbcf5b61d7c3782009fe825715e7e321be52aa1674fc964e1070/mkdocs-backlinks-0.9.1.tar.gz",
"platform": null,
"description": "# mkdocs-backlinks\n\nThis is a plugin for adding backlinks to your mkdocs generated pages.\n\nMkdocs is an awesome tool not only for documentation, but also for publishing [digital gardens](https://danodic.dev).\nBacklinks are a desirable component when building such digital gardens, as they enable the ability to explore content\nbased on how the knowledge interconnects instead of just looking at page navigation.\n\n## Setup\n\nInstall the plugin using pip:\n\n`pip install mkdocs-backlinks`\n\nActivate the plugin in `mkdocs.yml`:\n\n```yaml\nplugins:\n - mkdocs-backlinks\n```\n\n> **Note:** If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin.\n> MkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.\n\nMore information about plugins in the [MkDocs documentation][mkdocs-plugins].\n\n## Config\n\n* `ignored_pages` - A list of page titles that will be excluded from the backlinks.\n\n```yaml\nplugins:\n - mkdocs-backlinks:\n ignored_pages: [ 'Tags', 'Home' ] \n```\n\n## Usage\n\nThis plugin will add a `backlinks` attribute to the Jinja page context, which can be used to add backlinks at any point\nin your template. Here is an example of it:\n\n```html\n...\n\n{% if backlinks %}\n<h3>Backlinks:</h3>\n<ul>\n {% for backlink in backlinks %}\n <li><a href=\"/{{ backlink.url }}\">{{ backlink.title }}</a></li>\n {% endfor %}\n</ul>\n{% endif %}\n\n...\n```\n\nThat means **you need to have a template that supports backlinks**, or you can alter the template you are using with the\nsnippet above.\n\n### Writing Notes\n\nI have been using this to publish my Obsidian vault, and there are some _tricks_ to make it work well:\n\n- Obsidian is smart and will resolve links even if they don\u00b4t refer to a valid file path. This is not\n true for mkdocs and the backlinks plugin -- you need to write valid links in your markdown files, either\n absolute or relative links.\n- Absolute links are absolute related to the root of the `/docs` folder, not to your computer filesystem.\n\nFollowing those two rules will allow you to go straight from obsidian to mkdocs with cool backlinks.\n\n## See Also\n\nMore information about templates [here][mkdocs-template].\n\nMore information about blocks [here][mkdocs-block].\n\n[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/\n\n[mkdocs-template]: https://www.mkdocs.org/user-guide/custom-themes/#template-variables\n\n[mkdocs-block]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks\n\n## Thanks to\n\n- The creator of this awsome mkdocs plugin template: https://github.com/byrnereese/mkdocs-plugin-template\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin for adding backlinks to your documentation pages.",
"version": "0.9.1",
"split_keywords": [
"mkdocs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2e4fd2d6b59ab492510d23864e04c3dfb7398433b4c5579ea1a1055bacc53159",
"md5": "2bc1cdce06da29fc9cb52955a64f4d87",
"sha256": "71c80f2e14bc7cbddb431ea7f33e84a7b1acf85588b89a1cae2175f0157b998d"
},
"downloads": -1,
"filename": "mkdocs_backlinks-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2bc1cdce06da29fc9cb52955a64f4d87",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6089,
"upload_time": "2023-01-28T04:11:46",
"upload_time_iso_8601": "2023-01-28T04:11:46.107326Z",
"url": "https://files.pythonhosted.org/packages/2e/4f/d2d6b59ab492510d23864e04c3dfb7398433b4c5579ea1a1055bacc53159/mkdocs_backlinks-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c4d976b85008dbcf5b61d7c3782009fe825715e7e321be52aa1674fc964e1070",
"md5": "aa65a002b5247c1b50cd032b80476dc2",
"sha256": "0a1fefb4b7061948eccc0ad8b40cc34d729278f585e2a79b3ed8a3da050b80d6"
},
"downloads": -1,
"filename": "mkdocs-backlinks-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "aa65a002b5247c1b50cd032b80476dc2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 5672,
"upload_time": "2023-01-28T04:11:47",
"upload_time_iso_8601": "2023-01-28T04:11:47.246327Z",
"url": "https://files.pythonhosted.org/packages/c4/d9/76b85008dbcf5b61d7c3782009fe825715e7e321be52aa1674fc964e1070/mkdocs-backlinks-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-28 04:11:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "danodic-dev",
"github_project": "mkdocs-backlinks",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-backlinks"
}
JSON
