Versioned documentation

It would be nice to have a turnkey solution for projects that wish to support versioned documentation.

Requirements

Table stakes

• Each maintained branch gets its own set of docs
• Can publish from maintenance branches without breaking new things
• Can publish from main without breaking old things

Nice to have

• A new version updates the version selector in old versions
• EOL versions can easily point to a maintained version
• Version selector jumps to corresponding page, or a fallback if not relevant. (Laika does this.)
• If a PR will break the site generator, it fails. (A risk if mdoc compilation is separate from site generation.)

Extra credit

• /stable/* redirects to the latest stable version, like Read The Docs. This was possible on Netlify, which is an administrative headache. This is impossible on gh-pages.
• Works across repos for polyrepo projects (subdomains are a viable alternative)
• EOL versions are not indexed by Google. (Maybe. This would improve SEO within the site, but could hurt it to the site.)

Prior art

http4s

The /docs directory on live branches publishes to a subdirectory of the gh-pages branch. The /website directory is published off main and contains the project information that pertains to all branches.

Because each branch publishes independently, there is no way to update the theme across the board, nor a way to automatically update the version selector on old branches when release statuses change. Care must be taken to not touch anything outside that subdirectory.

cats-effect

I don't know how it works. Submodules and stuff. Generates crufty PRs, but the end user experience is best-in-Typelevel.

Monix

Has also been doing it for years in an artisanal fashion.

Other Scala projects that do a nice job and are worth studying

• Akka
• Play

Other tooling

Laika has multiple version support, and sbt-typelevel already integrates Laika

Other ideas

All of these are based on the idea that the site generator runs once, instead of independent sites per version and for the common area. This raises a basic tradeoff:

• If the site generator runs in the CI of a branch, we have a race condition
• If the site generator is triggered by a workflow after a branch is merged, that branch can break the site

Publish mdocs per branch, separate job generates the site

Requires careful git exclusions. Is the most economical with CI time.

mdoc all the branches and generate the site in one job

Awfully slow for large projects.

Parallelize building all branches, upload artifacts, generate in separate job

It's a heavy build, but it avoids git exclusions

Study the versioning approaches described for http4s, cats-effect, Monix, Akka, Play, Laika, and sbt-typelevel. Compare the listed CI and publishing options, including branch builds, a single all-branches build, and artifact parallelization. Done means an agreed turnkey approach that addresses the unchecked EOL, stable-redirect, cross-repository, and indexing requirements.