Metadata-Version: 2.4
Name: mkdocs-related-content-plugin
Version: 0.1.0
Summary: Properdocs/MkDocs plugin that computes, for every tagged page, a list of related pages based on shared tags, and exposes it to the Jinja context.
Author-email: Julien Moura <dev@ingeoveritas.com>
Maintainer-email: Julien Moura <dev@ingeoveritas.com>
License-Expression: MIT
Project-URL: Changelog, https://github.com/guts/mkdocs-related-content/blob/main/CHANGELOG.md
Project-URL: Documentation, https://guts.github.io/mkdocs-related-content/
Project-URL: Homepage, https://guts.github.io/mkdocs-related-content/
Project-URL: Issues, https://github.com/guts/mkdocs-related-content/issues/
Project-URL: releasenotes, https://github.com/guts/mkdocs-related-content/releases/latest
Project-URL: Repository, https://github.com/guts/mkdocs-related-content/
Keywords: documentation,Jaccard,mkdocs,plugin,properdocs,related,see also,similarity,tags
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff>=0.16.1; extra == "dev"
Requires-Dist: pre-commit<5,>=4.6.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-git-committers-plugin-2<2.6,>=2.4.1; extra == "docs"
Requires-Dist: mkdocs-materialx[imaging]<11,>=10.2.0; extra == "docs"
Requires-Dist: mkdocstrings-python<2.1,>=1.16.2; extra == "docs"
Requires-Dist: mkdocs-rss-plugin; extra == "docs"
Requires-Dist: termynal<0.15,>=0.12.2; extra == "docs"
Provides-Extra: test
Requires-Dist: mkdocs-materialx[imaging]<11,>=10.2.0; extra == "test"
Requires-Dist: pytest-cov<8,>=6.9.1; extra == "test"
Dynamic: license-file

# Static related contents - Properdocs / MkDocs plugin

[![PyPi version badge](https://badgen.net/pypi/v/mkdocs-related-content)](https://pypi.org/project/mkdocs-related-content/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-related-content)](https://pypi.org/project/mkdocs-related-content/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs-related-content)](https://pypi.org/project/mkdocs-related-content/)

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Guts_mkdocs-related-content&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Guts_mkdocs-related-content)
[![codecov](https://codecov.io/gh/Guts/mkdocs-related-content/branch/main/graph/badge.svg?token=A0XPLKiwiW)](https://codecov.io/gh/Guts/mkdocs-related-content)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Guts/mkdocs-related-content/main.svg)](https://results.pre-commit.ci/latest/github/Guts/mkdocs-related-content/main)
[![📚 Documentation](https://github.com/Guts/mkdocs-related-content/actions/workflows/documentation.yml/badge.svg)](https://github.com/Guts/mkdocs-related-content/actions/workflows/documentation.yml)

A plugin for [Properdocs](https://properdocs.org) / [MkDocs](https://www.mkdocs.org), the static site generator, which computes, for every tagged page, a list of related pages based on shared tags, and exposes it to the Jinja context so your theme can render a "Related content" / "See also" section.

## Installation

```sh
pip install mkdocs-related-content
```

## Usage

Then in your `mkdocs.yml`:

```yaml
plugins:
  - related-content
```

### Example

Two pages sharing a tag:

```yaml
# docs/api-auth.md
---
tags:
    - API
    - authentication
    - Python
---
```

```yaml
# docs/api-oauth.md
---
tags:
    - API
    - oAuth
---
```

Both pages `api-auth.md` and `api-oauth.md` share the `api` tag: each will list the other as related content ([Jaccard similarity score](https://fr.wikipedia.org/wiki/Indice_et_distance_de_Jaccard) of `0.25`), regardless of the order pages are declared in `nav`.

## Development

Once you cloned the repository:

```sh
# install project as editable
python -m pip install -e .

# including development dependencies
python -m pip install -e .[dev]

# including documentation dependencies
python -m pip install -e .[docs]

# including testing dependencies
python -m pip install -e .[test]

# all inclusive
python -m pip install -e .[dev,docs,test]

# install git hooks
pre-commit install
```

Then follow the [contribution guidelines](CONTRIBUTING.md).

### Run the tests

```sh
# install development dependencies
python -m pip install -e .[test]

# run tests
pytest
```

### Build the documentation

```sh
# install dependencies for documentation
python -m pip install -e .[docs]

# build the documentation
mkdocs build
```

### Release workflow

1. Fill the `CHANGELOG.md`
1. Change the version number in `__about__.py`
1. Apply a git tag with the relevant version: `git tag -a 0.3.0 {git commit hash} -m "New awesome feature"`
1. Push tag to main branch: `git push origin 0.3.0`
