Adds a backlinks section that lists every page linking to the current page.

The added backlinks section looks like this, but you can also customize the title and the text show above the list:

I wrote my plugin after trying some existing plugins and not being 100% happy with them. But depending on your intended use case, they may be a better fit.

My plugin is similar in concept to mkdocs-backlinks, but I wanted a plugin that works out of the box.

With mkdocs-backlinks you can specify exactly where and how you want to have your backlinks shown, but at the cost of having to potentially alter your template files.

With my plugin you can just add it to your mkdocs.yml without any theme changes. But it can also work the same way as mkdocs-backlinks, so that you have full control over the output.

mkdocs-publisher is a bundle of plugins. The pub-obsidian also has a backlinks feature.

While my plugin does a single job and has minimal dependencies, mkdocs-publisher offers many more features but at the cost of many more dependencies.

You can install it with pip:

pip install mkdocs-backlinks-section-plugin

Add the plugin to your mkdocs.yml:

plugins:
- search
- backlinks_section

You can customize the text inserted by the plugin with the configuration values below:

So for example if you would want the text to be in German, you could do this in your mkdocs.yml:

plugins:
- search
- backlinks_section:
    title: Rückverweise
    description: "Die folgenden Seiten referenzieren die aktuelle Seite:"
    description_no_links: Es gibt keine Verweise auf diese Seite.

You can ignore source and destination pages for the backlink section. The values are interpreted as glob-like patterns, which are matched against the paths of the Markdown source files.

For example you may have a page listing all tags (and thus linking to almost all pages) and want to prevent every page having a backlink to it:

plugins:
- search
- backlinks_section:
    ignore_links_from:
    - path/with/globs/**/to/tags.md

If you do not want a backlinks section on some pages, you can disable it with the ignore_links_to option:

plugins:
- search
- backlinks_section:
    ignore_links_to:
    - path/with/globs/**/to/files-without-backlink-section-*.md
    - index.md

If you do not want a backlinks section to be added to the table of contents of search page, you can set the add_to_toc parameter to false:

plugins:
- search
- backlinks_section:
    add_to_toc: false

If you want to hide the backlinks section from pages which have no backlinks, you can set the hide_if_empty attribute to true. Please note that in the current implementation this also requires always hiding the section title (even if the section exists) from the table of contents. To suppress the warning about this it is recommended to explicitly set add_to_toc to false too:

plugins:
- search
- backlinks_section:
    add_to_toc: false
    hide_if_empty: true

Similar to mkdocs-backlinks, this plugin also exposes backlinks to the page template. This allows you much more control about how and where to display your backlinks. If you want to use this feature, you can stop the plugin from adding a section:

plugins:
- search
- backlinks_section:
    add_section: false

If you want to use this side by side with the mkdocs-backlinks plugin or your theme expects the variable to be named something else, you can change the name of the Jinja variable that the plugin writes to:

plugins:
- search
- backlinks_section:
    add_section: false
    jinja_variable_name: backlinks_section_plugin

And then add some code for backlinks to your theme (see this MkDocs Material page, for other themes you need to figure that part out on your own):

{% if backlinks %}
<h3>Backlinks:</h3>
<ul>
    {% for backlink in backlinks %}
    <li><a href="/{{ backlink.url }}">{{ backlink.title }}</a></li>
    {% endfor %}
</ul>
{% endif %}

Used by me to debug problems with backlink generation. If you open a GitHub issue, it would be best to provide me a minimum working example, with which I can reproduce your problem. If that is not possible (for example because your project is private), it would help me if you supply the output of mkdocs when you set debug: True.

• Added Jinja support and jinja_variable_name option (see #6). By default, this plugin works as a replacement for danodic-dev/mkdocs-backlinks. You can change the jinja_variable_name to something else, so that both plugins can co-exist.

• Fixed backlinks not working when folder names contain special characters (see #5)

• Fixed false positive warnings about missing hrefs for tags starting with <a (<autoref>, <audio>, etc). Thank you @kzndotsh (see #4)

• Fixed an issue with backlinks not appearing on some pages (see #3)
• Added debug option to help with troubleshooting

• Ignore empty link tags created by listings with line numbers (linenums="1")
• In warning messages show which file caused the warning

• Added add_to_toc option, which controls whether to add the backlinks section to the table of contents.
• Added hide_if_empty option, which will hide the backlinks section, if no backlinks exist. This requires add_to_toc to be false, otherwise the table of contents would point to a potentially non-existent section.

• Fixed crash with Python <= 3.12

• Added ignore_links_from and ignore_links_to configuration options

• Initial version