Static related contents - Properdocs / MkDocs plugin

A plugin for Properdocs / MkDocs, 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

pip install mkdocs-related-content

Usage

Then in your mkdocs.yml:

plugins:
  - related-content

Example

Two pages sharing a tag:

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

# 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 of 0.25), regardless of the order pages are declared in nav.

Development

Once you cloned the repository:

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

Run the tests

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

# run tests
pytest

Build the documentation

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

# build the documentation
mkdocs build

Release workflow

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