Starlight Documentation Platform
================================

This note records the current docs-platform strategy for `voiage` in case the
project later migrates from Sphinx to a Starlight-based site.

Baseline Decision
-----------------

* Starlight is the candidate docs-site platform, not a silent replacement for
  the current Sphinx docs.
* The platform plan should pin a specific Starlight version family and record
  upgrade/update steps explicitly when the version changes.
* The default search path should stay on Pagefind unless a later decision
  justifies a different provider.

Required Plugins
----------------

* `starlight-versions` for versioned docs pages and release-aligned navigation.
* `starlight-links-validator` for broken-link validation in the docs site.

Conditional Plugins
-------------------

These are useful if the eventual Starlight site needs the corresponding UX:

* `starlight-image-zoom`
* `starlight-heading-badges`
* `starlight-sidebar-topics`
* `starlight-utils`

Migration Boundary
------------------

The current Sphinx documentation remains authoritative until a later
implementation track explicitly changes the primary docs site. Any future
Starlight migration must preserve:

* the current docs content hierarchy
* version-aware navigation
* link validation
* docs build and content smoke checks

This note is intentionally conservative so later implementation work can follow
the recorded baseline without reopening the platform decision.