mkdocs-techdocs-version-selector 0.1.2

MkDocs plugin that builds TechDocs versions from catalog-info.yaml

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

pip install mkdocs-techdocs-version-selector

Configuration

Configure the plugin in mkdocs.yml:

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"]
      techdocs_no_docker: true

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
• techdocs_no_docker (bool, default: true): appends --no-docker to techdocs-cli generate

Example multiversion.json

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

{
  "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)