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. 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.
Install the plugin using pip:
pip install mkdocs-backlinks
Activate the plugin in mkdocs.yml
:
plugins:
- mkdocs-backlinks
Note: If you have no
plugins
entry in your config file yet, you'll likely also want to add thesearch
plugin. MkDocs enables it by default if there is noplugins
entry set, but now you have to enable it explicitly.
More information about plugins in the MkDocs documentation.
ignored_pages
- A list of page titles that will be excluded from the backlinks.
plugins:
- mkdocs-backlinks:
ignored_pages: [ 'Tags', 'Home' ]
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:
...
{% 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.
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.
More information about templates here.
More information about blocks here.
- The creator of this awsome mkdocs plugin template: https://github.com/byrnereese/mkdocs-plugin-template