Publish versioned CodeMirror 5 and CodeMirror 6 homepages and demos

[haoranyu]

Summary

Outcome update (2026-08-25): #62 superseded the prominent header switcher with quieter contextual version links in each homepage and demo hero. The routes, one-action generation change, and version-local Home behavior remain unchanged.

Publish a maintained CodeMirror 5 homepage and real demo alongside the default CodeMirror 6 site, with a clear version switcher between them.

GitHub Pages supports a maximum of one project site per repository, and a branch-based publishing source selects only one branch/folder. Therefore, main and v1 cannot each expose independent Pages roots from this repository at the same time. The supported solution is one custom GitHub Actions deployment that assembles both versioned sites into a single static artifact.

Official references:

• What is GitHub Pages?
• Configuring a publishing source
• Using custom workflows with GitHub Pages

This work is deliberately separate from #49. Issue #49 remains the runtime, wire-compatibility, and v2 release gate; this issue owns the multi-version documentation and demo deployment.

Decision

Keep one Pages site and preserve all current CM6 URLs:

Public route	Content	Source
/	CodeMirror 6 / package v2 homepage	exact deployed main commit
/demo/	real CodeMirror 6 demo	exact deployed main commit
/migration/	CM5 → CM6 migration guide	exact deployed main commit
/v1/	CodeMirror 5 / package v1 homepage	pinned full commit SHA from v1
/v1/demo/	real CodeMirror 5 demo	the same pinned v1 commit

The root site remains canonical for CM6. We should not move it to /v2/, because that would break the existing homepage, demo, migration, and inbound links. Lightweight /v2/ and /v2/demo/ redirects may be added later for symmetry, but must canonicalize to the existing root URLs.

Goals

• Let a CM5 user reach version-correct installation guidance and a working CM5 demo without reading CM6 instructions.
• Let users switch between the CM5 and CM6 homepages or corresponding demos in one action.
• Keep the v1 website source maintained on the v1 branch while retaining main as the only production deployment authority.
• Make every deployment reproducible from two exact source commits and safe to roll back.
• Preserve the exact public author credit: Haoran Yu & Jisuanke Team.

Non-goals

• A second custom domain or an independent Pages site for the same repository.
• A new gh-pages branch; the permanent repository branches remain main and v1.
• Combining CodeMirror 5 and CodeMirror 6 in one demo runtime.
• Changing the recording format or converting stored recordings.
• Making v1 deploy directly from a floating branch head.
• Publishing npm packages; registry release work remains in Add a transaction-native CodeMirror 6 recorder and player #49.

User stories

• As an existing CM5 user, I can open a maintained CM5 homepage, copy a v1-safe install command, and run a genuine CM5 record/replay demo.
• As a prospective user, I can compare the supported editor generations and switch to the right homepage or demo without going through GitHub.
• As a migrating user, I can move from the CM5 site to the CM6 site and migration guide while keeping stored recordings unchanged.
• As a maintainer, I can identify the exact main and v1 commits behind the live site and reproduce or roll back the artifact.

P0 requirements

Version navigation

• Add a visible, keyboard-operable CM5/CM6 switcher to both homepages and both demo headers.
• The homepage switcher maps CM6 / ↔ CM5 /v1/.
• The demo switcher maps CM6 /demo/ ↔ CM5 /v1/demo/.
• Each demo has a visible Home link that stays within its editor generation.
• Expose the active choice with aria-current; version identity must not rely on color alone.
• Keep a direct migration link from the CM5 experience to /migration/.

Correct the v1 site before publishing it

The current v1 static site is complete enough to reuse, but it must be corrected in the v1 source itself rather than rewritten during deployment:

• self-canonicalize and set Open Graph URLs to /v1/ and /v1/demo/;
• replace stale v1.1.6 labels/cache keys with maintained v1 metadata;
• replace bare npm install codemirror-record with codemirror-record@^1 codemirror@^5 and show codemirror-record@cm5 as the explicit maintenance selector;
• point source/API links to the v1 branch, not default main;
• add the CM6 homepage and migration links;
• add the exact meta/footer author credit Haoran Yu & Jisuanke Team;
• add the missing Home link to the CM5 demo;
• retain a real CM5 runtime and the committed v1 bundle.

Deterministic Pages assembly

• Replace the current legacy main:/ Pages source with a custom Actions workflow.
• Keep the workflow and assembler owned by main.
• Store a full pinned v1 commit SHA in a main-tracked source manifest. The assembler must fail unless that commit is reachable from origin/v1 and its package major is 1.
• Check out the exact triggering main commit and the exact pinned v1 commit.
• Treat the v1 checkout as static input: never execute scripts from it in the deployment job.
• Copy an explicit allowlist rather than either whole repository. At minimum, v1 may contribute index.html, homepage.css, and the required demo/ HTML/CSS/JS/license assets.
• Keep custom-domain ownership at the Pages repository setting. Do not copy v1's CNAME or any second root metadata.
• Publish a provenance file or deployment summary containing both exact source SHAs.
• Reject symlinks/hardlinks, missing required assets, unexpected copied files, duplicate root ownership, and path/case mismatches.
• Give the deploy job only contents: read, pages: write, and id-token: write; keep the github-pages environment restricted to main.
• Serialize production deployments with a Pages concurrency group.
• Pull requests may build and upload a review artifact but must never deploy. Only a merged main commit or an authorized manual run from main may deploy.

Release-accurate copy

The live site must not claim that v2 is installable from latest or cm6 until #49 has verified those npm tags and codemirror-record@2.0.0. If this issue deploys first, use accurate release-candidate wording and update it after the registry gate. CM5 instructions must always remain explicitly on ^1 or cm5.

P1 requirements

• Add self-canonicalized /v2/ and /v2/demo/ redirects for symmetric bookmarks.
• Add versioned entries to a sitemap.
• Add a small, human-readable “source commits” link or deployment summary.
• Share the version-switcher styling without coupling the two editor runtimes.

Acceptance criteria

• /, /demo/, /migration/, /v1/, and /v1/demo/ return 200 on the custom domain; every referenced local CSS/JS asset returns 200.
• Existing CM6 URLs and anchors remain valid.
• Both homepages and both demos have correct bidirectional contextual version guidance (the prominent header switcher was superseded by Move version guidance out of the site headers #62) and version-local Home behavior.
• The CM5 and CM6 demos each complete a browser smoke path: edit → serialize → load → play, with the expected final document and no page, console, or network errors.
• Static checks cover version-specific install commands, npm/branch links, titles, descriptions, canonical/Open Graph URLs, version markers, and the exact author credit.
• Accessibility checks cover keyboard navigation, visible focus, landmarks, labels/status output, and reasonable narrow-screen behavior.
• Artifact tests prove the allowlist, exactly one site root/custom-domain policy, no links or copied files outside the approved set, and provenance for both source SHAs.
• The pinned v1 SHA is a full commit reachable from v1; changing it requires a reviewed main pull request.
• A pull request cannot deploy, and a production deploy cannot start until existing main CI has passed.
• A post-deploy check validates all five live routes, both real demos, canonical URLs, version links, and both source SHAs.
• A rollback procedure is documented and exercised: redeploy the previous known-good artifact or restore legacy main:/ Pages without changing DNS.

Delivery sequence

1. Merge an issue-numbered PR into v1 that corrects and links its homepage/demo and adds v1-side content tests.
2. Merge an issue-numbered PR into main that adds the switcher, pinned-source manifest, allowlisted assembler, artifact tests, browser checks, and Pages workflow.
3. Pin the reviewed v1 merge commit in the main PR.
4. Change Pages from legacy branch publishing to GitHub Actions while preserving codemirror-record.haoranyu.com.
5. Deploy, run the live smoke gate, and record both source SHAs on this issue.
6. Close only after the acceptance checklist is complete.

Success measures

• All five canonical routes and their local assets pass automated and live link checks.
• Both real demos pass the same record/replay smoke contract.
• A user can change editor generation from any homepage or demo with one direct navigation.
• Every production deployment identifies two immutable source SHAs and can be rolled back without branch-history changes.

[haoranyu]

Implementation status — 2026-08-25

The versioned-site implementation is ready, but production cutover is intentionally gated on the stable npm v2 release.

Completed on v1:

• Publish the CodeMirror 5 versioned site #54 publishes the CM5 homepage and real demo under /v1/ and /v1/demo/, with bidirectional version navigation, a version-local Home link, migration guidance, and the exact Haoran Yu & Jisuanke Team credit.
• Self-host the CodeMirror 5 demo runtime #56 self-hosts the exact CodeMirror 5.65.21 runtime, so the demo does not depend on blocked/flaky CDNs.
• Self-host v1 artwork and refresh CI actions #57 self-hosts the project artwork and updates CI to current action runtimes.
• All three PRs were merged through green CI; the pinned v1 source is 16bafb5cf2cc065bd8f18bccdca6232c5ad87844.

Ready on main:

• Publish versioned CodeMirror 5 and 6 sites #55 assembles /, /demo/, /migration/, /v1/, and /v1/demo/ into one deterministic Pages artifact from exact main and v1 commits.
• The workflow uses an explicit asset allowlist, rejects unsafe inputs, records both source SHAs, prevents PR deployment, and skips stale-main deployments.
• Its four required checks are green on Node 20/22/24 plus a real offline browser smoke test for all five routes and both recorder/player demos.
• The downloaded CI artifact matches the locally verified artifact byte-for-byte except for the expected PR merge-ref provenance SHA.

Still pending by design:

• The registry currently has latest=1.1.6, cm5=1.1.8, no cm6 tag, and no codemirror-record@2.0.0.
• Therefore Publish versioned CodeMirror 5 and 6 sites #55 remains open and the live Pages source remains unchanged. This avoids advertising an unavailable stable v2.
• After the exact v2 artifact is published and verified under cm6 and then promoted to latest, the remaining sequence is: switch Pages to Actions, merge the green Publish versioned CodeMirror 5 and 6 sites #55 PR, verify the custom domain and all five live routes/demos, record the deployed source SHAs here, then close this issue.

[haoranyu]

Cutover readiness update — 2026-08-25

PR #55 has been rebased onto the final green main release commit and is currently mergeable/clean.

• Head: 1bb52adc24c7e0b72546dc49c6d33e93a1512869
• Node 20.19/22.13/24: passed
• Build and smoke-test versioned Pages: passed with all external HTTP(S) assets blocked
• Review artifact: versioned-pages-review-55-6f6a7d82902108acd3e32910bcb62c7c1b0cfc8d
• Artifact provenance: main PR merge ref 6f6a7d82902108acd3e32910bcb62c7c1b0cfc8d, pinned v1 16bafb5cf2cc065bd8f18bccdca6232c5ad87844
• Routes: /, /demo/, /migration/, /v1/, /v1/demo/
• PR deployment: skipped as required

The current production settings were re-audited and left unchanged: legacy main:/, custom domain codemirror-record.haoranyu.com, the existing HTTPS-enforcement value, and a github-pages environment policy limited to main.

The only cutover blocker remains npm authorization. The exact v2 tarball passed every retained-artifact gate, but npm web/2FA authorization expired while the Mac was locked, so 2.0.0, cm6, and latest remain unchanged. #55 must not merge until those three registry assertions pass. After they do, re-enable the Pages build as a required main check, switch Pages to Actions, merge #55, and run the live five-route/demo verification before closing this issue.

[haoranyu]

Completed through #54, #56, #57, and #55.

• GitHub Pages now publishes through the protected main workflow while preserving the existing custom domain and HTTPS-enforcement setting.
• The deployed source provenance is main=52fda497e8369cd336f0c0879d4b8037feb09bd1 and pinned v1=16bafb5cf2cc065bd8f18bccdca6232c5ad87844.
• The production run passed the full Node matrix, immutable assembly, both-generation demo smoke test, stale-deployment guard, and deployment: https://github.com/Jisuanke/CodeMirror-Record/actions/runs/32799087166.
• All 24 published files were compared byte-for-byte with that run artifact over the custom HTTPS origin.
• /, /demo/, /migration/, /v1/, and /v1/demo/ all passed live browser verification, including version switchers, demo Home links, author credit, and real capture/load/play flows in both CodeMirror generations.

The versioned homepage and demo contract is live and verified, so this issue can be closed.