docs: redesign site with shared versioned guides and API references

[arturcic]

Summary

Redesign the documentation site and generate versioned guides and API references with one shared Wyam2 theme. Readers can switch between 7.0, 6.8, and 5.12 without losing their page, and choose light or dark mode.

• Refresh the landing page, documentation navigation, API layout, and responsive styling. Place the version selector beside the theme switch.
• Render released prose from its exact tag and API signatures from matching Tool, Core, and MSBuild packages. Cache immutable inputs and record their provenance; do not reuse generated gh-pages content.
• Sort numbered editions newest first and redirect root URLs to the highest edition. Keep 7.0 backed by the checkout until its first stable release, then automatically switch it to published inputs. Discover subsequent stable minor editions from v7 onward.
• Preserve legacy /5.12.0/ URLs and keep archived redirects within their edition. List only GitVersion assemblies while retaining dependencies for type resolution.
• Use Cake.Wyam for builds and local preview, validate public API coverage and local links, and expand the docs workflow triggers to cover source/build changes.
• Update v7 guidance and provide source-build instructions while no v7 package is published.

Validation

• Full documentation build passed for 7.0, 6.8, and 5.12, including documentation sample tests, Mermaid checks, public API inventory, and local links.
• All 17 input-selection checks passed, including numeric ordering and development-to-stable transition.
• Browser checks passed for root redirects, query/fragment preservation, version switching, legacy aliases, and released MSBuild API pages.
• Source-publish instructions verified locally; docs build project compiles with no warnings or errors.
• Workflow actionlint, scoped dotnet format verification, and git diff checks passed. GitHub workflow results are pending.

Screenshots

Landing page — light

Landing page — dark

Documentation and version selector

Fixes #4537.

Fixes #5187.

[Copilot]

🟡 Changes recommended

There are a few confirmed runtime/UX issues (version switching on homepages, clipboard fallback robustness, and a misleading manifest validation message) that should be fixed before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR overhauls the docs/ site to support multiple concurrently published documentation editions (7.0 dev, 6.8, 5.12), adds a version selector + theme toggle in a shared Wyam2/Samson theme, and updates the build pipeline to generate versioned guides + API reference from tag-accurate inputs.

Changes:

• Introduces a versioned documentation build that resolves released prose/API inputs per edition, caches immutable inputs, and generates edition-aware redirects/manifests.
• Redesigns the documentation UI (new homepage, navigation grouping, API layouts) and adds light/dark theme support.
• Expands CI workflow triggers/steps to validate edition selection and cache documentation inputs for faster, repeatable builds.

File summaries

File	Description
docs/versions.json	Defines explicit editions and release discovery baseline for docs builds.
docs/theme/assets/js/versions.js	Adds client-side version selector behavior using generated manifests/routes.
docs/scripts/check-docs-inputs.cs	Adds script-based validation checks for input selection and manifest constraints.
docs/readme.md	Documents the new versioned docs organization, inputs, and local preview workflow.
docs/input/Shared/Sidebar/_Namespace.cshtml	Adds namespace tree rendering for API sidebar navigation.
docs/input/Shared/Sidebar/_ChildPages.cshtml	Adds v7+ curated sidebar grouping and shows current docs edition label.
docs/input/Shared/Section/_DocsTable.cshtml	Adds a reusable table section for API index lists (with optional summaries).
docs/input/index.cshtml	Replaces the landing page with redesigned homepage content and edition-aware commands.
docs/input/docs/usage/index.cshtml	Reworks “Usage” into “Guides” landing page with curated task links.
docs/input/docs/usage/configure.md	Adds a new guide for creating/inspecting GitVersion.yml.
docs/input/docs/usage/cli/output.md	Rewrites CLI output guidance around JSON/single-var/file/buildserver/dotenv usage.
docs/input/docs/usage/ci.md	Refocuses CI page to point to provider guides and key anchors.
docs/input/docs/usage/choose-workflow.md	Adds a new “choose a workflow” guide and clarifies workflow vs behavior.
docs/input/docs/reference/version-sources.md	Renames/reframes “Version Sources” into “Calculation strategies” and preserves anchors.
docs/input/docs/reference/variables.md	Clarifies that variable output snippet is illustrative (not tied to a specific branch).
docs/input/docs/reference/requirements.md	Updates shallow clone guidance and v7 argument naming.
docs/input/docs/reference/modes/index.cshtml	Reworks “Versioning Modes” page into a comparison table for deployment modes.
docs/input/docs/reference/mdsource/configuration.source.md	Updates source-of-truth configuration reference intro and trunk-based labeling.
docs/input/docs/reference/index.cshtml	Reworks “Reference” landing page into curated links and updated ordering.
docs/input/docs/reference/environment-variables.md	Adds new guidance distinguishing inputs vs exported outputs and v7 compatibility notes.
docs/input/docs/reference/configuration.md	Updates generated configuration reference intro to match the new framing.
docs/input/docs/reference/configuration-topics/output.md	Adds “Output and formatting” topic page.
docs/input/docs/reference/configuration-topics/index.md	Adds “Configuration by topic” landing page plus alphabetical settings index.
docs/input/docs/reference/configuration-topics/calculation.md	Adds “Version calculation” topic page.
docs/input/docs/reference/configuration-topics/branches.md	Adds “Branch configuration” topic page.
docs/input/docs/reference/build-servers/index.cshtml	Reworks build-server page into “CI integrations” with clearer setup steps.
docs/input/docs/migration/index.cshtml	Reworks “Migration” into “Upgrading” with v7-development clarity.
docs/input/docs/learn/workflows-modes-strategies.md	Adds a new conceptual page separating workflows/modes/strategies.
docs/input/docs/learn/index.cshtml	Reworks “Learn” into “Concepts” with curated reading order.
docs/input/docs/learn/how-it-works.md	Rewrites calculation overview into a step-based explanation, preserving key anchors.
docs/input/docs/learn/git-setup.md	Reframes “Git Setup” as “Repository setup” and clarifies remotes vs requirements.
docs/input/docs/learn/faq.md	Reworks FAQ into “Troubleshooting” with diagnostics and updated links.
docs/input/docs/learn/branching-strategies/index.cshtml	Renames/reframes examples as “Workflow examples” and adds workflow-first guidance.
docs/input/docs/learn/branching-strategies/contribute-examples.md	Hides “Contribute Examples” from the sidebar.
docs/input/docs/index.cshtml	Reworks docs landing page into a curated “start here / explore” layout.
docs/input/docs/getting-started/index.md	Adds new “Getting started” guide including v7 source-build instructions.
docs/input/assets/js/theme.js	Adds theme toggle logic with system preference + localStorage persistence.
docs/input/assets/js/site.js	Adds API “On this page” TOC generation and copy-to-clipboard behavior for homepage.
docs/input/assets/css/redesign.css	Adds extensive redesign styling for homepage/docs/API layouts + dark theme palette.
docs/input/_Navbar.cshtml	Updates navbar: removes confusing “latest/5.12.0” link and adds version selector + theme switch.
docs/input/_Master.cshtml	Introduces a new master layout and integrates redesigned header/sidebar/footer structure.
docs/input/_Head.cshtml	Adds redesign stylesheet, theme script, and version selector script includes.
docs/input/_Footer.cshtml	Adds a new footer with brand and community/contributor links.
docs/input/_Bottom.cshtml	Removes legacy GitHub button and adds site JS bundle include.
docs/input/_ApiLayout.cshtml	Adds a new API page layout with breadcrumb, TOC panel, and consistent styling.
docs/input/_ApiIndex.cshtml	Adds a new API index page listing namespaces with summaries.
build/docs/Utilities/VersionedDocs.cs	Implements multi-edition render, asset hashing, link prefixing, redirects, and manifests.
build/docs/Utilities/DocsValidation.cs	Adds build-time validation for required pages, redirects, API coverage, and local links.
build/docs/Utilities/DocsLinks.cs	Adds helpers for stripping query/fragment and parsing meta refresh targets.
build/docs/Utilities/DocsInputs.cs	Implements edition resolution, release discovery, caching, and provenance receipts.
build/docs/Utilities/DocsApi.cs	Builds public API inventories/routes and supplements XML docs from tagged source.
build/docs/Tasks/PublishDocs.cs	Switches publishing to copy the prepared preview output (no reuse of prior gh-pages content).
build/docs/Tasks/PreviewDocs.cs	Uses the new versioned preview server path (serves assembled site).
build/docs/Tasks/PrepareDocsInputs.cs	Adds task to resolve/cache documentation inputs before rendering.
build/docs/Tasks/BuildDocs.cs	Switches BuildDocs to versioned build pipeline.
build/docs/docs.csproj	Adds AngleSharp + Roslyn C# packages; removes Cake.Npx usage.
build/docs/BuildLifetime.cs	Removes legacy shared Wyam settings initialization (now driven by VersionedDocs).
build/docs/BuildContext.cs	Replaces WyamSettings with PreparedEdition[] inputs in build context.
build/Directory.Packages.props	Adds central versions for AngleSharp and Microsoft.CodeAnalysis.CSharp.
.gitignore	Ignores local agent planning notes directory /.devagent/.
.github/workflows/docs.yml	Expands triggers, adds input-selection checks, caches docs inputs, and updates htmlproofer args.

Review details

• Files reviewed: 60/61 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The generated versions.json routes currently represent the edition root index.html as /index, which breaks “preserve current page” behavior for homepage version switching.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 60/61 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

The docs workflow’s HTMLProofer invocation is likely broken by an invalid --assume-extension argument, and the new preview rebuild timer is constructed in a way that can trigger an immediate unnecessary rebuild/race.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 60/61 changed files
• Comments generated: 3
• Review effort level: Lite

[asbjornu]

Amazing work, @arturcic! 👏🏼 🎉

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[Copilot]

🟡 Changes recommended

There are a couple of concrete issues (notably an accessibility bug in the theme toggle labeling and a misleading/ineffective routes filter) that should be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 60/61 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

The workflow docs-input cache key forces a new cache per run (quota/efficiency risk) and redirect validation currently doesn’t associate alias redirect pages with an edition, reducing coverage for the “stay within edition” constraint.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 60/61 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

The publish job’s docs-input cache key includes github.run_id, which will create a new cache entry every run and can quickly exhaust Actions cache quota.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 60/61 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[mergify]

Thank you @arturcic for your contribution!