Metadata-Version: 2.4
Name: mkdocs-techdocs-version-selector
Version: 0.1.3
Summary: MkDocs plugin that builds TechDocs versions from catalog-info.yaml
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: MkDocs
Classifier: Topic :: Documentation
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: mkdocs>=1.5
Requires-Dist: PyYAML>=6.0

# mkdocs-techdocs-version-selector

MkDocs plugin that builds versioned TechDocs static sites from version mappings defined directly in `mkdocs.yml`.

## What it does

- Reads versions from plugin config (`versions`) in `mkdocs.yml`
- Does nothing when there are no configured versions or only one configured version
- Builds each configured git branch/tag into a dedicated subdirectory (for example `site/__v2`, `site/__v3`)
- Writes `multiversion.json` for the TechDocs version selector
- Adds a root/default manifest entry using `root_version_name` (with path `/`)
- Prevents recursive re-execution during child version builds

## Installation

```bash
pip install mkdocs-techdocs-version-selector
```

## Configuration

Configure the plugin in `mkdocs.yml`:

```yaml
plugins:
  - techdocs-version-selector:
      root_version_name: latest
      versions:
        - v2: v2
        - v3: v3
      site_subdir_prefix: "__"
      manifest_filename: multiversion.json
      techdocs_cli_command: ["techdocs-cli"]
```

### Config reference

- `versions` (list): list of one-entry maps where key = version label and value = git branch/tag
  - Example: `- v2: release/2.0`
- `root_version_name` (string, default: `root`): display name written for the default/root docs version in `multiversion.json`
- `site_subdir_prefix` (string, default: `__`): prefix for version output folders under `site/`
- `manifest_filename` (string, default: `multiversion.json`): manifest filename under `site/`
- `techdocs_cli_command` (list, default: `["techdocs-cli"]`): command used to run TechDocs generation

## Example `multiversion.json`

After a successful build, `site/multiversion.json` will look like:

```json
{
  "latest": {
    "name": "latest",
    "latest": true,
    "path": "/"
  },
  "v2": {
    "name": "v2",
    "latest": false,
    "ref": "v2",
    "path": "/__v2/"
  },
  "v3": {
    "name": "v3",
    "latest": false,
    "ref": "v3",
    "path": "/__v3/"
  }
}
```

## Requirements

- Python 3.9+
- `mkdocs`
- `git` available on `PATH`
- `techdocs-cli` available on `PATH` (or configure `techdocs_cli_command`)
