myst-version-switcher-plugin¶
A pydata-style documentation version switcher for MyST,
delivered as a single anywidget plugin plus reusable CI workflows that build
your docs and reconstruct the whole versioned site from durable sources every deploy,
publishing it directly to GitHub Pages.
The two halves are versioned together under one vX.Y.Z tag but consumed
differently — the plugin as a release asset, the workflows by uses: at that tag:
| What | Where |
|---|---|
| Plugin (widget) | plugins/version-switcher.mjs → a release-asset URL in myst.yml plugins |
| Reusable CI workflows | .github/workflows/{docs,publish}.yml → uses: …/.github/workflows/{docs,publish}.yml@<tag> in your ci.yml |
| Source | https:// |
| Documentation | https:// |
| Releases | https:// |
The single .mjs is both the build-time MyST plugin and the browser runtime — MyST
localises it into your site, so there is no second asset to host. The publish.yml
workflow rebuilds the complete site every deploy (the default branch’s build, each
release’s docs.zip, every open PR’s artifact), so deletions self-heal and there is
no gh-pages branch to drift.
The dropdown in the top-right corner of this page is the plugin itself. It also works in any page body:
How the documentation is structured¶
Documentation is split into four categories, also accessible from the links in the top bar.
Add versioned docs to a fresh repo, start to finish. New users start here.
Practical step-by-step guides — e.g. migrating from an existing gh-pages site.
How the reconstruct-from-sources model works, and why it works that way.
The version-switcher directive options and the assemble action contract.