# MkDocs Backlinks Section Plugin
[](https://pypi.org/project/mkdocs-backlinks-section-plugin/)
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:
## Comparison to similar plugins
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.
### mkdocs-backlinks
My plugin is similar in concept to [mkdocs-backlinks](https://github.com/danodic-dev/mkdocs-backlinks), but I wanted a plugin that works out of the box.
With [mkdocs-backlinks](https://github.com/danodic-dev/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 just need to add the plugin to your `mkdocs.yml`, but the backlinks can only be added as a section at the bottom of each page.
### mkdocs-publisher
[mkdocs-publisher](https://github.com/mkdocs-publisher/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.
## Installation
You can install it with `pip`:
```bash
pip install mkdocs-backlinks-section-plugin
```
## Usage
Add the plugin to your `mkdocs.yml`:
```yaml
plugins:
- search
- backlinks_section
```
## Configuration
### Text
You can customize the text inserted by the plugin with the configuration values below:
Option | Type | Default value
--- | --- | ---
`title` | string | `Backlinks`
`description` | string | `The following pages link to this page:`
`description_no_links` | string | `No other pages link to this page.`
So for example if you would want the text to be in German, you could do this in your `mkdocs.yml`:
```yaml
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.
```
### Ignore pages
You can ignore source and destination pages for the backlink section.
The values are interpreted as [glob-like](https://docs.python.org/3/library/pathlib.html#pathlib-pattern-language) patterns, wich are matched against the paths of the Markdown source files.
Option | Type | Default value
--- | --- | ---
`ignore_links_from` | list of strings | `[]`
`ignore_links_to` | list of strings | `[]`
For example you may have a page listing all [tags](https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/) (and thus linking to almost all pages) and want to prevent every page having a backlink to it:
```yaml
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:
```yaml
plugins:
- search
- backlinks_section:
ignore_links_to:
- path/with/globs/**/to/files-without-backlink-section-*.md
- index.md
```
### Hide section
Option | Type | Default value
--- | --- | ---
`add_to_toc` | boolean | `true`
`hide_if_empty` | boolean | `false`
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`:
```yaml
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:
```yaml
plugins:
- search
- backlinks_section:
add_to_toc: false
hide_if_empty: true
```
### Troubleshooting
Option | Type | Default value
--- | --- | ---
`debug` | boolean | `false`
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`.
## Notable changes
### Version 0.0.6
- Fixed an issue with backlinks not appearing on some pages (see #3)
- Added `debug` option to help with troubleshooting
### Version 0.0.5
- Ignore empty link tags created by listings with line numbers (`linenums="1"`)
- In warning messages show which file caused the warning
### Version 0.0.4
- 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.
### Version 0.0.3
- Fixed crash with Python <= 3.12
### Version 0.0.2
- Added `ignore_links_from` and `ignore_links_to` configuration options
### Version 0.0.1
- Initial version
Raw data
{
"_id": null,
"home_page": "https://github.com/six-two/mkdocs-backlinks-section-plugin",
"name": "mkdocs-backlinks-section-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "six-two",
"author_email": "pip@six-two.dev",
"download_url": "https://files.pythonhosted.org/packages/ba/c7/c51af65e8ae62d00548512a6dde55cb72345448f78c29929aaa3568ba1c5/mkdocs_backlinks_section_plugin-0.0.6.tar.gz",
"platform": null,
"description": "# MkDocs Backlinks Section Plugin\n\n[](https://pypi.org/project/mkdocs-backlinks-section-plugin/)\n\n\n\nAdds a backlinks section that lists every page linking to the current page.\n\nThe added backlinks section looks like this, but you can also customize the title and the text show above the list:\n\n\n\n## Comparison to similar plugins\n\nI wrote my plugin after trying some existing plugins and not being 100% happy with them.\nBut depending on your intended use case, they may be a better fit.\n\n### mkdocs-backlinks\n\nMy plugin is similar in concept to [mkdocs-backlinks](https://github.com/danodic-dev/mkdocs-backlinks), but I wanted a plugin that works out of the box.\n\nWith [mkdocs-backlinks](https://github.com/danodic-dev/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.\n\nWith my plugin you just need to add the plugin to your `mkdocs.yml`, but the backlinks can only be added as a section at the bottom of each page.\n\n### mkdocs-publisher\n\n[mkdocs-publisher](https://github.com/mkdocs-publisher/mkdocs-publisher) is a bundle of plugins.\nThe `pub-obsidian` also has a backlinks feature.\n\nWhile my plugin does a single job and has minimal dependencies, mkdocs-publisher offers many more features but at the cost of many more dependencies.\n\n## Installation\n\nYou can install it with `pip`:\n```bash\npip install mkdocs-backlinks-section-plugin\n```\n\n## Usage\n\nAdd the plugin to your `mkdocs.yml`:\n```yaml\nplugins:\n- search\n- backlinks_section\n```\n\n## Configuration\n\n### Text\n\nYou can customize the text inserted by the plugin with the configuration values below:\n\nOption | Type | Default value\n--- | --- | ---\n`title` | string | `Backlinks`\n`description` | string | `The following pages link to this page:`\n`description_no_links` | string | `No other pages link to this page.`\n\n\nSo for example if you would want the text to be in German, you could do this in your `mkdocs.yml`:\n```yaml\nplugins:\n- search\n- backlinks_section:\n title: R\u00fcckverweise\n description: \"Die folgenden Seiten referenzieren die aktuelle Seite:\"\n description_no_links: Es gibt keine Verweise auf diese Seite.\n```\n\n### Ignore pages\n\nYou can ignore source and destination pages for the backlink section.\nThe values are interpreted as [glob-like](https://docs.python.org/3/library/pathlib.html#pathlib-pattern-language) patterns, wich are matched against the paths of the Markdown source files.\n\nOption | Type | Default value\n--- | --- | ---\n`ignore_links_from` | list of strings | `[]`\n`ignore_links_to` | list of strings | `[]`\n\nFor example you may have a page listing all [tags](https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/) (and thus linking to almost all pages) and want to prevent every page having a backlink to it:\n\n```yaml\nplugins:\n- search\n- backlinks_section:\n ignore_links_from:\n - path/with/globs/**/to/tags.md\n```\n\nIf you do not want a backlinks section on some pages, you can disable it with the `ignore_links_to` option:\n```yaml\nplugins:\n- search\n- backlinks_section:\n ignore_links_to:\n - path/with/globs/**/to/files-without-backlink-section-*.md\n - index.md\n```\n\n### Hide section\n\nOption | Type | Default value\n--- | --- | ---\n`add_to_toc` | boolean | `true`\n`hide_if_empty` | boolean | `false`\n\nIf 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`:\n```yaml\nplugins:\n- search\n- backlinks_section:\n add_to_toc: false\n```\n\nIf you want to hide the backlinks section from pages which have no backlinks, you can set the `hide_if_empty` attribute to `true`.\nPlease note that in the current implementation this also requires always hiding the section title (even if the section exists) from the table of contents.\nTo suppress the warning about this it is recommended to explicitly set `add_to_toc` to `false` too:\n```yaml\nplugins:\n- search\n- backlinks_section:\n add_to_toc: false\n hide_if_empty: true\n```\n\n### Troubleshooting\n\nOption | Type | Default value\n--- | --- | ---\n`debug` | boolean | `false`\n\nUsed by me to debug problems with backlink generation.\nIf you open a GitHub issue, it would be best to provide me a minimum working example, with which I can reproduce your problem.\nIf 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`.\n\n## Notable changes\n\n### Version 0.0.6\n\n- Fixed an issue with backlinks not appearing on some pages (see #3)\n- Added `debug` option to help with troubleshooting\n\n### Version 0.0.5\n\n- Ignore empty link tags created by listings with line numbers (`linenums=\"1\"`)\n- In warning messages show which file caused the warning\n\n### Version 0.0.4\n\n- Added `add_to_toc` option, which controls whether to add the backlinks section to the table of contents.\n- Added `hide_if_empty` option, which will hide the backlinks section, if no backlinks exist.\n This requires `add_to_toc` to be false, otherwise the table of contents would point to a potentially non-existent section.\n\n### Version 0.0.3\n\n- Fixed crash with Python <= 3.12\n\n### Version 0.0.2\n\n- Added `ignore_links_from` and `ignore_links_to` configuration options\n\n### Version 0.0.1\n\n- Initial version\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Adds a backlinks section that lists every page linking to the current page.",
"version": "0.0.6",
"project_urls": {
"Homepage": "https://github.com/six-two/mkdocs-backlinks-section-plugin"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "32eb13b13dab74f7c1905610f138e3d3920c6de7d03d2545e52f2b5f9a9abac9",
"md5": "2d78d1c77e1c4f2e58d301a17512361e",
"sha256": "615d93a36b5cd3c08f006628a961e787247a477edb9a73f4b448de97596210c4"
},
"downloads": -1,
"filename": "mkdocs_backlinks_section_plugin-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d78d1c77e1c4f2e58d301a17512361e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8470,
"upload_time": "2025-07-31T18:27:39",
"upload_time_iso_8601": "2025-07-31T18:27:39.062370Z",
"url": "https://files.pythonhosted.org/packages/32/eb/13b13dab74f7c1905610f138e3d3920c6de7d03d2545e52f2b5f9a9abac9/mkdocs_backlinks_section_plugin-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bac7c51af65e8ae62d00548512a6dde55cb72345448f78c29929aaa3568ba1c5",
"md5": "51239508b6987eba1b16afe0b6cec268",
"sha256": "c977cdb242e4ba1037163be92b872cc9be29602b30624eb5f8030b908f018b83"
},
"downloads": -1,
"filename": "mkdocs_backlinks_section_plugin-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "51239508b6987eba1b16afe0b6cec268",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 8023,
"upload_time": "2025-07-31T18:27:40",
"upload_time_iso_8601": "2025-07-31T18:27:40.324399Z",
"url": "https://files.pythonhosted.org/packages/ba/c7/c51af65e8ae62d00548512a6dde55cb72345448f78c29929aaa3568ba1c5/mkdocs_backlinks_section_plugin-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 18:27:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "six-two",
"github_project": "mkdocs-backlinks-section-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-backlinks-section-plugin"
}
JSON
