feat(docs): add version selector

    rules:

      - changes:

          - docs/**/*

  # Zola template (GitLab Pages variant)

  - component: "$CI_SERVER_FQDN/to-be-continuous/zola/gitlab-ci-zola-pages@1.1"

    rules:

      - changes:

          - docs/**/*

  - component: "$CI_SERVER_FQDN/to-be-continuous/gitlab-butler/gitlab-ci-butler@1.4"

    inputs:

      pipelines-delete-older-than: "30"

# Build and publish versioned documentation to GitLab Pages

# Replaces the to-be-continuous zola-pages component with a custom job

# that builds all documentation versions (main->latest, develop->dev, tags)

pages:

  stage: publish

  image: alpine:latest

  rules:

    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"'

    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "develop"'

    - if: "$CI_COMMIT_TAG"

  before_script:

    - apk add --no-cache bash curl git

    # Install Zola static site generator

    - ZOLA_VERSION="0.19.2"

    - echo "Installing Zola v${ZOLA_VERSION}..."

    - curl -sL "https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-x86_64-unknown-linux-musl.tar.gz" | tar xz -C /usr/local/bin

    - zola --version

  script:

    - git submodule update --init --recursive

    - bash scripts/build-versioned-docs.sh

  artifacts:

    paths:

      - public

# The Butler image ships with a binary entrypoint. Clear it so GitLab Runner

# can execute the generated shell wrapper instead of appending it as CLI args

# to `gitlab-butler`.

+++

title = "Appendix"

render = false

[extra]

hide_from_toc = true

description = "Supplementary reference information."

sort_by = "weight"

template = "section.html"

+++

+++

title = "Versioning"

title = "Documentation Versions"

weight = 1

+++

# Versioning

# Documentation Versions

See the [Changelog](@/reference/changelog.md) for full version history.

This documentation site is published in several versions that correspond to the

plugin's release cycle.

| Version | Source | Description |

|---------|--------|-------------|

| latest | `main` branch | Current stable release. Updated with every push to `main`. |

| dev | `develop` branch | In-progress changes. May include unreleased features. |

| vX.Y.Z | Git tags | Point-in-time snapshot for each tagged release. |

## How versions work

The documentation is built from three sources:

- **`main` branch** — published as the **latest** version. These docs match

  the most recent stable plugin release.

- **`develop` branch** — published as **dev**. These docs may cover features

  that aren't yet shipped. Use these to preview upcoming changes.

- **Git tags** — each tagged release (`vX.Y.Z`) gets its own snapshot so you can

  browse the docs that were current when that version was published.

## Switching versions

Use the version picker in the top navigation bar to switch between versions.

The version picker shows:

- **latest** — the current stable documentation (shown with a badge)

- **dev** — bleeding-edge documentation from the develop branch

- **vX.Y.Z** — point-in-time snapshots for each tagged release

When you switch to a different version, the URL changes to include the version

path. You can also bookmark version-specific URLs directly.

## See also

- [Changelog](@/reference/changelog.md) — full version history of the plugin

{# Sidebar with Table of Contents for Docs Mode #}

{# Sidebar with Table of Contents for Docs Mode — project override removes hardcoded "v" prefix #}

<aside id="sidebar" class="sidebar" role="complementary" aria-labelledby="sidebar-title">

    {# Resize handle (desktop only) #}

    <div class="sidebar__resize-handle" aria-hidden="true" title="Drag to resize sidebar width"></div>

            {% if root_section.subsections %}

            {% for subsection_path in root_section.subsections %}

            {% set subsection = get_section(path=subsection_path) %}

            {% if subsection.extra.hide_from_toc is not defined or not subsection.extra.hide_from_toc %}

            <div class="toc__section">

                <a href="{{ subsection.permalink | safe }}" class="toc__section-title {% if current_path is defined and current_path == subsection.path %}active{% endif %}">{{ subsection.title }}</a>

                <ul class="toc__list">

                    {% endfor %}

                </ul>

            </div>

            {% endif %}

            {% endfor %}

            {% endif %}

            {% endif %}

    <div class="sidebar__footer">

        {# Mobile-only actions (hidden on desktop where they're in header) #}

        <div class="sidebar__actions-mobile">

            {# Version picker #}

            {% if config.extra.versions is defined %}

            <div class="sidebar__action">

                <span class="sidebar__action-label">Version</span>

                <div class="sidebar__version">

                    <span class="sidebar__version-current">{{ config.extra.versions.current }}</span>

                    {% for v in config.extra.versions.list %}

                    {% if v.version != config.extra.versions.current %}

                    <a href="{{ v.url | safe }}" class="sidebar__version-link">{{ v.version }}</a>

                    {% endif %}

                    {% endfor %}

                </div>

            </div>

            {% endif %}

            {# Theme toggle #}

            {% if config.extra.show_theme_toggle | default(value=true) %}

            <div class="sidebar__action">

{# Version Picker Dropdown (docs mode only) — project override removes hardcoded "v" prefix #}

{% if config.extra.versions %}

{% set current_version = config.extra.versions.current | default(value="latest") %}

<div class="version-picker">

    <button class="version-picker__button" aria-haspopup="listbox" aria-expanded="false">

        <span>{{ current_version }}</span>

        {% for v in config.extra.versions.list %}

        {% if v.version == current_version and v.label is defined %}

        <span class="version-picker__badge">{{ v.label }}</span>

        {% endif %}

        {% endfor %}

        <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">

            <path d="m6 9 6 6 6-6"/>

        </svg>

    </button>

    <div class="version-picker__dropdown" role="listbox">

        {% for v in config.extra.versions.list %}

        <a href="{{ v.url | safe }}" class="version-picker__item {% if v.version == current_version %}active{% endif %}" role="option">

            {{ v.version }}

            {% if v.label is defined and v.label %}

            <span class="version-picker__badge">{{ v.label }}</span>

            {% endif %}

        </a>

        {% endfor %}

        <hr class="version-picker__divider">

        <a href="{{ get_url(path='appendix/versioning/') | safe }}" class="version-picker__item version-picker__item--link">

            All versions

            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">

                <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/>

                <polyline points="15 3 21 3 21 9"/>

                <line x1="10" y1="14" x2="21" y2="3"/>

            </svg>

        </a>

    </div>

</div>

{% endif %}