[#2595] Added path-based documentation versioning with v1/v2 CI aggregation.

[AlexSkrypnyk]

Closes #2595

Summary

Added path-based documentation versioning to the Docusaurus site. Multi-version mode turns on automatically when a versioned_docs/ snapshot is present: v1 (a snapshot of the building branch's docs) is served at the bare /docs as the default, and v2 (pulled from project/2.x) is served at /docs/v2 with an unreleased banner and a navbar version dropdown. A /docs/v1 -> /docs redirect keeps the explicit v1 path valid. With no snapshot - local development, per-branch preview builds, and the docusaurus docs:version run that creates the snapshot - the site builds content/ as a single unversioned set, so the config never references a version that does not exist yet.

Three .mdx files that import repo-root files were switched from depth-relative ../../../../ paths to the depth-independent @site/../.. alias, so they still resolve when content/ is relocated into versioned_docs/ during the CI assembly step.

Both publish workflows gain a matching "Assemble versioned docs" step that snapshots the building branch's docs as 1.x, then fetches and swaps in project/2.x's content as the current (v2) version before building. vortex-release.yml (production / GitHub Pages) runs it unconditionally; vortex-test-docs.yml (development / Netlify) runs it only on main, so PR and feature-branch previews stay single-version. The step guards each git operation and verifies the branch exists before removing content, so a missing or failed project/2.x fetch can never publish an empty docs site. The assembled versioned_docs/ is gitignored and never committed.

Changes

.vortex/docs/docusaurus.config.js - The multi-version config (the versions block with v1 as lastVersion at the bare /docs, v2 at path v2 with an unreleased banner, the docsVersionDropdown navbar item, and a /docs/v1 -> /docs client redirect) is gated on fs.existsSync('versioned_docs'), so it applies only when the snapshot exists and produces no output otherwise.

.vortex/docs/content/contributing/code-of-conduct.mdx, .vortex/docs/content/drupal/composer-json.mdx, .vortex/docs/content/drupal/settings.mdx - Replaced depth-relative imports (../../../../) with the @site/../.. alias so they remain valid when the file is copied into versioned_docs/version-1.x/ during CI assembly.

.github/workflows/vortex-release.yml and .github/workflows/vortex-test-docs.yml - Added a guarded "Assemble versioned docs" step before the build (docusaurus docs:version 1.x, then fetch + verify origin/project/2.x and swap its docs into content/). The release workflow runs it always; the test-docs workflow runs it only on main. The build then auto-detects the assembled snapshot - no environment flag.

.vortex/docs/.gitignore - Ignore versioned_docs/, versioned_sidebars/, and versions.json (assembled in CI for the published site, or locally to preview the multi-version build; never committed).

Before / After

BEFORE (single-version, always)
───────────────────────────────
/docs            → current content (one version, no dropdown)

CI publish flow:
  yarn build
  → single-version GitHub Pages / Netlify site

AFTER (single-version on PRs/branches, multi-version on main/release)
──────────────────────────────────────────────────────────────────────
Local dev / PR preview  (no versioned_docs/ snapshot):
  /docs            → current content (unchanged, no dropdown)

main / release build  (snapshot assembled in CI, auto-detected):
  /docs            → versioned_docs/version-1.x  (v1, default)
  /docs/v2         → content/ from project/2.x   (v2, "unreleased" banner)
  /docs/v1         → redirect to /docs

CI publish flow (vortex-release.yml always; vortex-test-docs.yml on main):
  yarn docusaurus docs:version 1.x     # snapshot building-branch docs as v1
  git fetch origin project/2.x         # guarded fetch + branch verification
  rm -rf content && checkout 2.x docs  # swap in v2 content
  yarn build                           # auto-detects versioned_docs/ -> multi-version
  → versioned GitHub Pages / Netlify site with dropdown

Summary by CodeRabbit

• Documentation

  • Multi-version docs: preserved v1 snapshot while serving v2 alongside, with version chooser and redirects for discoverability.
  • Fixed embedded examples and policy asset references so code samples and conduct docs render reliably.

• Chores

  • CI now assembles the versioned documentation site automatically and ignores generated version artifacts in the docs tree.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 66bdbb7a-f4e6-4b13-bc0c-660f77476654

📥 Commits

Reviewing files that changed from the base of the PR and between 28987bb and 574de24.

📒 Files selected for processing (7)

• .github/workflows/vortex-release.yml
• .github/workflows/vortex-test-docs.yml
• .vortex/docs/.gitignore
• .vortex/docs/content/contributing/code-of-conduct.mdx
• .vortex/docs/content/drupal/composer-json.mdx
• .vortex/docs/content/drupal/settings.mdx
• .vortex/docs/docusaurus.config.js

---

Walkthrough

CI workflows snapshot current docs as v1, fetch project/2.x content into the docs workspace, and set a versioned flag. Docusaurus config conditionally serves v1 at /docs and v2 at /docs/v2 with a dropdown and redirect. MDX imports use @site aliases and generated version artifacts are gitignored.

Changes

Documentation Versioning System

Layer / File(s)	Summary
CI assemble versioned docs .github/workflows/vortex-release.yml, .github/workflows/vortex-test-docs.yml	Adds Assemble versioned docs steps that run Docusaurus docs:version 1.x, fetch origin/project/2.x, remove local .vortex/docs/content, and check out project/2.x's .vortex/docs/content into the workspace.
Docusaurus config: conditional versioned routing .vortex/docs/docusaurus.config.js	Introduces versioned detection (presence of versioned_docs) and, when enabled, sets lastVersion: '1.x', maps current docs to path: 'v2' with an "unreleased" banner, adds a docsVersionDropdown navbar item, and a client redirect from /docs/v1 to /docs.
MDX import path normalization .vortex/docs/content/contributing/code-of-conduct.mdx, .vortex/docs/content/drupal/composer-json.mdx, .vortex/docs/content/drupal/settings.mdx	Replaces deep relative ../../.. raw-loader/imports with @site/../../... aliases for CODE_OF_CONDUCT, composer.json, and Drupal snippet examples so embedded code/markdown resolves consistently across versioned builds.
Docs gitignore for generated version artifacts .vortex/docs/.gitignore	Adds ignore rules and comments for versioned_docs, versioned_sidebars, and versions.json produced by docusaurus docs:version or CI assembly.

sequenceDiagram
  participant GitHubActions
  participant DocusaurusCLI
  participant GitOrigin
  participant Workspace
  GitHubActions->>DocusaurusCLI: yarn docusaurus docs:version 1.x
  DocusaurusCLI->>Workspace: create versioned_docs (version-1.x)
  GitHubActions->>GitOrigin: git fetch origin project/2.x
  GitHubActions->>Workspace: remove .vortex/docs/content
  GitHubActions->>GitOrigin: checkout .vortex/docs/content from project/2.x into workspace
  GitHubActions->>GitHubActions: set DOCS_VERSIONED env flag
  GitHubActions->>DocusaurusCLI: build documentation site

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

A2

"🐰 I hopped through branches, nibbling docs in two,
I stored v1 in a burrow and let v2 bloom anew,
I stitched imports with @site and nudged the checkout through,
Now readers may hop between halls with guidance true. 🥕"

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: implementing path-based documentation versioning with CI aggregation for v1/v2.
Linked Issues check	✅ Passed	All acceptance criteria from issue #2595 are met: docs serve both 1.x and 2.x with versioning [vortex-release.yml, vortex-test-docs.yml], 1.x is frozen [docusaurus.config.js], 2.x is editable [project/2.x branch integration], version switcher is implemented [docsVersionDropdown], and import paths are resilient [.mdx files with @site alias].
Out of Scope Changes check	✅ Passed	All changes are within scope: workflow modifications for CI assembly, docusaurus config for versioning, .mdx import path updates for relocation resilience, and gitignore additions for versioned artifacts.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/2595-docs-versioning

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Around line 13-17: Update the README.md CI badges that currently target the
URL-encoded branch "project%2F2.x" to point to the repository's default branch
"main" (or add an explicit note that the badges intentionally track
"project/2.x"); specifically update the badge links for "Database, Build, Test
and Deploy", "CircleCI", "Test", "Test docs" and the codecov badge so their
branch query/path uses "main" instead of "project%2F2.x" to ensure the badges
reflect the default branch CI status.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8c128876-fa48-4c91-a5d2-cb1e6421643f

📥 Commits

Reviewing files that changed from the base of the PR and between 35711bd and f493c1a.

📒 Files selected for processing (7)

• .github/workflows/vortex-release.yml
• .github/workflows/vortex-test-docs.yml
• .vortex/docs/content/contributing/code-of-conduct.mdx
• .vortex/docs/content/drupal/composer-json.mdx
• .vortex/docs/content/drupal/settings.mdx
• .vortex/docs/docusaurus.config.js
• README.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.11%. Comparing base (5b5661c) to head (574de24).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2601      +/-   ##
==========================================
- Coverage   86.56%   86.11%   -0.46%     
==========================================
  Files          94       87       -7     
  Lines        4661     4502     -159     
  Branches       47        3      -44     
==========================================
- Hits         4035     3877     -158     
+ Misses        626      625       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/vortex-release.yml:
- Around line 161-167: The Assemble versioned docs step deletes content before
verifying git operations; change the sequence so you first verify that git fetch
and checkout of origin/project/2.x succeed (e.g., perform git fetch origin
project/2.x --depth=1 and attempt git checkout origin/project/2.x --
.vortex/docs/content into a temporary location or test the checkout exit code),
and only run rm -rf content and replace it if those commands returned success;
ensure the step fails fast on fetch/checkout errors or uses an atomic move to
avoid leaving the repo without docs.

In @.github/workflows/vortex-test-docs.yml:
- Around line 97-101: The workflow currently runs destructive rm -rf content
before verifying git operations; update the step around git -C "${{
github.workspace }}" fetch origin project/2.x --depth=1 and git -C "${{
github.workspace }}" checkout origin/project/2.x -- .vortex/docs/content to fail
fast and only remove content after a successful fetch/checkout: either enable
shell errexit (set -e) for the run block or explicitly check the exit status of
the fetch and checkout commands, aborting (exit 1) if they fail, and move rm -rf
content to occur only after the checkout completes successfully so you never
delete content when the branch is missing.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0d92404a-d208-4728-a7c6-b0a236316995

📥 Commits

Reviewing files that changed from the base of the PR and between 5822353 and 2d00138.

📒 Files selected for processing (6)

• .github/workflows/vortex-release.yml
• .github/workflows/vortex-test-docs.yml
• .vortex/docs/content/contributing/code-of-conduct.mdx
• .vortex/docs/content/drupal/composer-json.mdx
• .vortex/docs/content/drupal/settings.mdx
• .vortex/docs/docusaurus.config.js

[github-actions]

📖 Documentation preview for this pull request has been deployed to Netlify:

https://6a27f82723e9ce0687534b51--vortex-docs.netlify.app

This preview is rebuilt on every commit and is not the production documentation site.

[github-actions]

Code coverage (threshold: 90%)

  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   98.56% (205/208)

Per-class coverage

Drupal\ys_demo\Plugin\Block\CounterBlock
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 10/ 10)

[AlexSkrypnyk]

Code coverage (threshold: 90%)

  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   98.56% (205/208)

Per-class coverage

Drupal\ys_demo\Plugin\Block\CounterBlock
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 10/ 10)

[AlexSkrypnyk]

Code coverage (threshold: 90%)

  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   98.56% (205/208)

Per-class coverage

Drupal\ys_demo\Plugin\Block\CounterBlock
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 10/ 10)