mkdocs-git-version-title

A tiny MkDocs plugin that appends the current Git version to the MkDocs site title at build time.

It intentionally does one thing only: tell readers which Git version of the documentation they are looking at.

What it does

Given this mkdocs.yml:

site_name: AI Collaboration Protocol

plugins:
  - search
  - git-version-title

MkDocs renders a site title such as:

AI Collaboration Protocol (v1.2.0)

If the current commit is three commits after v1.2.0:

AI Collaboration Protocol (v1.2.0-3-g51bd920)

The source mkdocs.yml and Markdown files are not modified. The plugin changes site_name only in MkDocs' in-memory configuration during the build.

Installation

pip install mkdocs-git-version-title

Then enable it in mkdocs.yml:

plugins:
  - search
  - git-version-title

If your project already has a plugins: section, just add git-version-title to it.

Version resolution

The plugin runs:

git describe --tags --always

from the directory containing mkdocs.yml. Git will search parent directories for the repository as usual.

The resulting title follows these rules:

Repository state	Version shown
HEAD is exactly tagged	v1.2.0
HEAD is 3 commits after the nearest tag	v1.2.0-3-g51bd920
Git repository has no tags	51bd920
No Git repository, no commits, or Git is unavailable	unknown

Both annotated and lightweight tags are considered because the command uses --tags.

Why the site title?

The version belongs to the documentation project as a whole, not to each individual page. Putting it in site_name keeps every page uncluttered while making the currently viewed documentation version immediately visible.

The plugin deliberately does not add build dates, authors, branches, commit histories, or other repository metadata. Those details belong in Git/GitHub when they are needed.

CI builds

git describe can only describe history that exists in the checkout. In CI, make sure the checkout contains the tags and enough Git history to reach them. A shallow checkout with missing tags may fall back to a commit hash instead of the expected tag-based version.

No CI-specific environment variable is required. Version resolution remains part of the MkDocs build itself.

Local development

Create an environment and install the project in editable mode:

python -m venv .venv

Activate the environment, then run:

pip install -e ".[dev]"
pytest

To test it in a real MkDocs project:

pip install -e /path/to/mkdocs-git-version-title
mkdocs build

Build a distribution

python -m build

This creates a source distribution and wheel under dist/.

Before publishing:

twine check dist/*

Publish to PyPI

For a manual release:

twine upload dist/*

For a public project, PyPI Trusted Publishing from GitHub Actions is preferable to storing a long-lived PyPI API token in repository secrets.

After publication, users only need:

pip install mkdocs-git-version-title

Project layout

mkdocs-git-version-title/
├── pyproject.toml
├── README.md
├── LICENSE
├── CHANGELOG.md
├── src/
│   └── mkdocs_git_version_title/
│       ├── __init__.py
│       ├── plugin.py
│       └── version.py
├── tests/
│   ├── test_plugin.py
│   └── test_version.py
└── examples/
    └── mkdocs.yml

License

MIT