docs: add multi-version support and rebrand theme handling by balzss · Pull Request #2425 · instructure/instructure-ui

balzss · 2026-02-27T15:00:52Z

INSTUI-4917
INSTUI-4918

Summary

Multi-version docs support: The docs app can now serve documentation for multiple library minor versions (e.g. v11.6, v11.7). A version selector in the header lets users switch between versions. Each version loads its own component docs, theme variables, and interactive code examples with the correct component implementations.
Clean URL routing: Replaced hash-based routing with path-based URLs (e.g. /v11_7/Button instead of /#Button). Added support for PR preview path prefixes (/pr-preview/pr-XXXX/).
Removed component overrides generator: Simplified versioned component imports by removing the generate-component-overrides script and auto-generated component-overrides.ts. Components are now imported directly based on package.json exports.
Rebrand themes: Only show rebrand themes (Canvas and new themes) for version v11.7 and newer. Older versions show the legacy theme list.
Subcomponent theme variables fix: Fixed theme variables not displaying correctly for subcomponents (e.g. Calendar.Day).
PR preview routing fix: Set webpack publicPath dynamically for PR preview builds so assets load from the correct subdirectory on GitHub Pages. Prefixed all data fetch paths with the PR preview base path.

Test plan

Run pnpm run bootstrap — builds cleanly
Run pnpm run dev, open http://localhost:9090
Navigate to component pages — loads without console errors
Version dropdown appears in header, switching versions loads correct docs and code examples
Switch versions rapidly — no console errors from stale/aborted fetches
Verify rebrand themes only appear for v11.7+
Verify subcomponent theme variables display correctly (e.g. Calendar.Day)
Run pnpm run build:docs — verify __build__/docs-versions.json and per-version subdirectories exist
PR preview: push to a PR branch, verify https://instructure.design/pr-preview/pr-XXXX/ loads correctly

github-actions · 2026-02-27T15:05:52Z

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-03-06 17:47 UTC

matyasf

There is something off with theme variables for subcomponents, e.g. check Table or Menu
When I switch to v11.7 and reload the page I see v11.6. Would it be difficult to include in the URL the version I'm viewing?
Do not show the rebrand themes in the dropdown when its not ?beta (a hacky temp solution is OK)
We should either add to the themes docs e.g.g /rebrand-dark that these are only from 11.7 or not show them for 11.6

packages/__docs__/component-overrides.ts

packages/__docs__/package.json

packages/__docs__/buildScripts/build-docs.mts

matyasf · 2026-03-03T10:44:24Z

packages/__docs__/buildScripts/utils/buildVersionMap.mts

+
+  if (!fs.existsSync(exportFilePath)) {
+    // eslint-disable-next-line no-console
+    console.warn(


Shouldn't we throw an error in this case? as I understand this means, that the package.json specifies an export that does not exist

joyenjoyer · 2026-03-04T09:03:12Z

How do I switch back from beta mode, only with page reload?

balzss · 2026-03-04T09:04:56Z

How do I switch back from beta mode, only with page reload?

yes

joyenjoyer · 2026-03-04T09:12:58Z

docs/contributor-docs/docs-versioning.md

+pnpm run generate:component-overrides
+```
+
+## Adding a new library version (e.g. v11_23)


I like the documentation and how you addressed all the use cases, nice work

joyenjoyer · 2026-03-04T09:23:09Z

packages/__docs__/src/App/index.tsx

+    // triggered by the new docs uses the correct component references
+    updateGlobalsForVersion(newVersion)
+
+    // Clear current data to show loading screen, update selected version


Shouldn't state clearing come before calling updateGlobalsForVersion()? Could this cause any side effects?

the comment makes it a bit misleading, order doesn't really matter here. will update the comment

joyenjoyer · 2026-03-04T09:51:28Z

packages/__docs__/src/versionData.ts

  return undefined
 }

+type MinorVersionData = {


Just being nitpicky: a better place for this might be DataType.mts.

my reasoning was that this is used runtime and DataType.mts contains build time code, but that separation is already a bit blurry in the current way we use the docs app so I'll move it there for simplicity's sake

matyasf

looks good! Some smaller changes, see my comments

for me its a bit confusing that we're displaying now the same info at / and /v11_6/. Maybe route the oldest version to / and the others should have /vXY URLs?
We will have to do something with docs pages that change with minor version, e.g. /using-theme-overrides -- this should be a different doc for v11.6 and v11.7, but this can be in a new PR

docs/contributor-docs/docs-versioning.md

packages/__docs__/buildScripts/build-docs.mts

matyasf · 2026-03-04T17:15:11Z

packages/__docs__/src/App/index.tsx

+    const allThemeKeys = Object.keys(this.state.docsData!.themes)
+    const showRebrandThemes =
+      this.state.showMinorVersionSelector &&
+      this.state.selectedMinorVersion !== 'v11_6'


This feels very hardcoded, I hope in the future it wont cause issues

well, the fact that 11.6 has the old themes, and 11.7 has the new themes shouldn't change in the future so it feels strange but i think this is the correct way to do this. maybe a comment here would be nice to explain it

balzss · 2026-03-04T20:15:04Z

looks good! Some smaller changes, see my comments

for me its a bit confusing that we're displaying now the same info at / and /v11_6/. Maybe route the oldest version to / and the others should have /vXY URLs?

We will have to do something with docs pages that change with minor version, e.g. /using-theme-overrides -- this should be a different doc for v11.6 and v11.7, but this can be in a new PR

@matyasf

for me that would be also confusing since that would feel like v11_6 is missing. i guess the feature that we don't display the version selector by default is only temporary, so when we switch to always displaying it, it would be less confusing
good call, we should do that in the future

matyasf

Very nice work!

Just 2 small issues from me

docs/contributor-docs/docs-versioning.md

HerrTopi

The comment I left will be handled later, in https://instructure.atlassian.net/browse/INSTUI-4950

HerrTopi · 2026-03-06T14:53:48Z

packages/__docs__/versioned-components.ts

Could we generate/update this file during bump? I don't like to remember manual steps upon releases

balzss self-assigned this Feb 27, 2026

balzss force-pushed the docs-multi-version-support branch 3 times, most recently from 0476a3e to 1a36846 Compare March 2, 2026 13:01

balzss marked this pull request as ready for review March 2, 2026 13:10

balzss force-pushed the docs-multi-version-support branch 2 times, most recently from a1d236b to 8a0ec21 Compare March 2, 2026 15:45

balzss requested review from joyenjoyer and matyasf and removed request for matyasf March 2, 2026 17:05

matyasf requested changes Mar 3, 2026

View reviewed changes

joyenjoyer reviewed Mar 4, 2026

View reviewed changes

balzss force-pushed the docs-multi-version-support branch from 0be86da to b6b52d0 Compare March 4, 2026 13:06

balzss requested review from HerrTopi and joyenjoyer and removed request for joyenjoyer March 4, 2026 13:30

joyenjoyer removed their request for review March 4, 2026 13:37

balzss force-pushed the docs-multi-version-support branch from 31bfd5d to 640bf73 Compare March 4, 2026 13:50

balzss requested a review from matyasf March 4, 2026 13:51

balzss force-pushed the docs-multi-version-support branch from 640bf73 to ff8efad Compare March 4, 2026 14:01

balzss changed the title ~~docs: add multi-version support for docs~~ docs: add multi-version support and rebrand theme handling Mar 4, 2026

matyasf requested changes Mar 4, 2026

View reviewed changes

balzss force-pushed the docs-multi-version-support branch from ff8efad to 221140d Compare March 4, 2026 20:12

balzss requested a review from matyasf March 4, 2026 20:15

matyasf requested changes Mar 6, 2026

View reviewed changes

docs/contributor-docs/docs-versioning.md Show resolved Hide resolved

docs: add multi-version support for docs

1c1bbb2

balzss force-pushed the docs-multi-version-support branch from 221140d to 1c1bbb2 Compare March 6, 2026 10:34

matyasf approved these changes Mar 6, 2026

View reviewed changes

HerrTopi approved these changes Mar 6, 2026

View reviewed changes

balzss merged commit 6b5ceac into v12 Mar 6, 2026
7 of 9 checks passed

balzss deleted the docs-multi-version-support branch March 6, 2026 17:47

Conversation

balzss commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

github-actions bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joyenjoyer commented Mar 4, 2026

Uh oh!

balzss commented Mar 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joyenjoyer Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

balzss commented Mar 4, 2026

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

HerrTopi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

balzss commented Feb 27, 2026 •

edited

Loading

github-actions bot commented Feb 27, 2026 •

edited

Loading

joyenjoyer Mar 4, 2026 •

edited

Loading