docs-version.yml

# What this branch publishes.
#
# Read by .github/workflows/publish.yaml. Each `sites` entry becomes one
#     mike deploy --deploy-prefix <prefix> -F <config> <version> <aliases...>
#
# One documentation version per product MINOR version -- patch releases do not
# get their own. Each product has its own version axis and its own
# <prefix>/versions.json, so RIDDL shipping 2.1 does not renumber Synapify.
#
#   branch      publishes
#   ----------  ----------------------------------------------------------
#   main        EVERYTHING: the shell, riddl 1.31 + 2.0, riddlg 0.6,
#               synapify 0.17
#
# `main` is the only publishing branch (2026-07-31, TASK G). The RIDDL 1.x line
# used to publish from a `docs/1.x` branch; it is now sites/riddl-1x/ here, so
# both RIDDL versions build from one tree and share one copy of the chrome.
#
# That also RETIRES the old danger note, which warned that two branches must
# never declare the same prefix AND alias -- because --update-aliases MOVES an
# alias to the most recent deploy, a later push to the wrong branch could
# silently drag the site default back to 1.x. One branch cannot race itself, so
# promoting 2.0 is now an edit to this file alone: move `latest` from the 1.31
# entry to the 2.0 entry, in one commit. See scripts/promote-2.0-to-latest.md.
#
# Two entries share the `riddl` prefix on purpose. Each becomes its own mike
# deploy at its own version, and they coexist in one <prefix>/versions.json.
# Order matters for one thing only: `mike set-default` runs per entry, so the
# LAST riddl entry decides where /riddl/ redirects. Keep the entry holding
# `latest` last.

# The unversioned part of the site: landing page, About, Coming Soon. Deployed
# to the gh-pages root, without mike, because none of it tracks a product
# release. Only `main` publishes it.
shell:
  config: sites/shell/mkdocs.yml

sites:
  - prefix: riddl
    config: sites/riddl/mkdocs.yml
    version: "2.0"
    aliases:
      - next

  # `latest` deliberately stays on 1.31 until RIDDL 2.0 ships final. Promoting
  # it is scripts/promote-2.0-to-latest.md -- now a single edit to this file.
  #
  # MUST stay after the 2.0 entry: `mike set-default` runs once per entry, so
  # the last `riddl` entry is the one that decides where /riddl/ redirects.
  - prefix: riddl
    config: sites/riddl-1x/mkdocs.yml
    version: "1.31"
    aliases:
      - latest

  - prefix: riddlg
    config: sites/riddlg/mkdocs.yml
    version: "0.6"
    aliases:
      - latest

  - prefix: synapify
    config: sites/synapify/mkdocs.yml
    version: "0.17"
    aliases:
      - latest