Metadata-Version: 2.4
Name: mkdocs-git-version-title
Version: 0.1.0
Summary: Show the current Git describe version in the MkDocs site title.
License-Expression: MIT
Keywords: mkdocs,git,version,documentation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Plugins
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs<2,>=1.4
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

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

```yaml
site_name: AI Collaboration Protocol

plugins:
  - search
  - git-version-title
```

MkDocs renders a site title such as:

```text
AI Collaboration Protocol (v1.2.0)
```

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

```text
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

```bash
pip install mkdocs-git-version-title
```

Then enable it in `mkdocs.yml`:

```yaml
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:

```bash
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:

```bash
python -m venv .venv
```

Activate the environment, then run:

```bash
pip install -e ".[dev]"
pytest
```

To test it in a real MkDocs project:

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

## Build a distribution

```bash
python -m build
```

This creates a source distribution and wheel under `dist/`.

Before publishing:

```bash
twine check dist/*
```

## Publish to PyPI

For a manual release:

```bash
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:

```bash
pip install mkdocs-git-version-title
```

## Project layout

```text
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
