https://github.com/six-two/mkdocs-backlinks-section-plugin

Create a backlink section that lists every page linking to the current page
https://github.com/six-two/mkdocs-backlinks-section-plugin

backlinks mkdocs mkdocs-plugin

Last synced: about 10 hours ago
JSON representation

Create a backlink section that lists every page linking to the current page

• Host: GitHub
• URL: https://github.com/six-two/mkdocs-backlinks-section-plugin
• Owner: six-two
• License: mit
• Created: 2024-12-01T16:22:41.000Z (2 months ago)
• Default Branch: main
• Last Pushed: 2024-12-19T10:04:21.000Z (about 1 month ago)
• Last Synced: 2025-01-19T20:40:31.838Z (14 days ago)
• Topics: backlinks, mkdocs, mkdocs-plugin
• Language: Python
• Homepage:
• Size: 40 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# MkDocs Backlinks Section Plugin

[![PyPI version](https://img.shields.io/pypi/v/mkdocs-backlinks-section-plugin)](https://pypi.org/project/mkdocs-backlinks-section-plugin/)

![License](https://img.shields.io/pypi/l/mkdocs-backlinks-section-plugin)

![Python versions](https://img.shields.io/pypi/pyversions/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:

![Screenshot of the backlinks section](screenshot.png)

## Comparision 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

```

## Notable changes

### 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