docs: better multiversion support for docs v2 by git-nandor · Pull Request #2568 · instructure/instructure-ui

git-nandor · 2026-05-27T17:31:07Z

INSTUI-5031

Summary

Moves the component version (minor version) selector from the side nav to the component pages, displayed alongside the Theme selector
The Component version and Theme selectors are now only rendered on Components pages
The v11.6 option in the Component version Select is labeled v11.6 (legacy theming)
Restores the full library version display in the side nav header
Legacy Theme Overrides page always redirects to v11.6
New Theme Overrides page always redirects to v11.7
Adds an info alert on all non-component pages explaining that the content reflects the latest versioning
Modify New theme overrides page "13. Independent overrides for child parts of compound components" section
Adds a new "Component versioning" guide page

Co-Authored-By: 🤖 Claude

github-actions · 2026-05-27T17:36:32Z

PR Preview Action v1.8.1
🚀 View preview at https://instructure.design/pr-preview/pr-2568/
Built to branch `gh-pages` at 2026-06-12 08:32 UTC. Preview will be ready when the GitHub Pages deployment is complete.

github-actions · 2026-05-27T17:38:16Z

Visual regression report

✅ No changes.

Status	Count
Unchanged	32
Changed	0
New	0
Removed	0

📊 View full report

_{Baselines come from the visual-baselines branch. They refresh on every merge to master.}

matyasf

The "If you are viewing the v11.7 version, switch to v11.6 to see the examples working correctly." text in the legacy/new theme overrides is not needed anymore since the switch is automatic.
The message "This page always displays the latest version of the documentation" is not clear what it means. I would rephrase it to "This page is made for the latest version (v${major.minor})) of InstUI). Also the linked page https://instructure.design/pr-preview/pr-2568/v11_7/multi-version-system is way too detailed for our users, can you make a new page under Guides that explains the multi version stuff for users? We just need that components are now versioned, the import paths, and what versions work with which theming engine.
I would not include the Component version selector for non-component pages where it does nothing
+1: How about displaying components with the "Light" theme when switching to v11.7, since this is now the recommended theme?

matyasf

Nice work, I like these changes a lot!

balzss · 2026-06-09T12:09:45Z

+
+- **`v2`** (library `v11_7` and newer) supports themes built on the new token system. The legacy Canvas looks are preserved (re-implemented on the new engine) and two brand-new themes are added:
+
+  - `legacyCanvas` — same visual style as the old `canvas`, but on the new engine


This lists the v2 legacy themes as legacyCanvas / legacyCanvasHighContrast, but the new-theme-overrides page (v2) uses theme={canvas} throughout, and the docs Theme selector labels the v2 theme as canvas (legacy). Are the real v2 theme keys actually canvas / canvasHighContrast (shown as "(legacy)") rather than legacyCanvas / legacyCanvasHighContrast? If so the names here are misleading.

balzss · 2026-06-09T12:09:55Z

+          <Table.RowHeader>TableRowHeader — deeppink</Table.RowHeader>
+          <Table.Cell>TableCell — unchanged</Table.Cell>
+        </Table.Row>
+                <Table.Row>


Minor: this <Table.Row> is over-indented (extra leading spaces), and both Table.ColHeaders above share the same label and a copy-pasted id pattern (h-row / h-col). Quick tidy since it renders as an example.

balzss · 2026-06-09T12:09:58Z

+            <Alert variant="info" margin="xx-large 0">
+              This page is made for the latest version (
+              {this.getLatestMinorVersion()?.replace('_', '.')}) of InstUI.{' '}
+              <Link href="component-versioning">


This (and the same <Link href="component-versioning"> in Document/index.tsx) uses a bare relative href. Does it resolve correctly from a versioned URL like /v11_7/Alert — navigating within the SPA rather than triggering a full reload — given the deploy-base + v11_X prefix routing? Worth a quick check.

Thanks, fixed

…ponent versioning guide page

…page

…uide and bring up usage section on component pages

…# before navigateTo so markdown links produce clean URLs

…orrectly merged description

matyasf

nice work, the whole documentation is much better understandable now!

git-nandor self-assigned this May 27, 2026

github-actions Bot pushed a commit that referenced this pull request May 27, 2026

visual-regression: PR #2568 (b2aa05f) b2aa05f

dce45d6

git-nandor force-pushed the INSTUI-5031_better_multiversion_support_for_docs_v2 branch 2 times, most recently from 817d7d2 to d14ada1 Compare May 27, 2026 18:02

git-nandor force-pushed the rework-documentation branch from cf96591 to e713885 Compare May 28, 2026 07:53

git-nandor force-pushed the INSTUI-5031_better_multiversion_support_for_docs_v2 branch from d14ada1 to c60e824 Compare May 28, 2026 07:56

git-nandor marked this pull request as ready for review May 28, 2026 07:56

git-nandor requested review from HerrTopi, ToMESSKa, balzss, joyenjoyer and matyasf May 28, 2026 07:56

matyasf requested changes Jun 1, 2026

View reviewed changes

git-nandor force-pushed the rework-documentation branch from e713885 to ced0fb5 Compare June 2, 2026 12:37

git-nandor force-pushed the INSTUI-5031_better_multiversion_support_for_docs_v2 branch from c60e824 to 7e3bad3 Compare June 3, 2026 08:25

git-nandor requested a review from matyasf June 3, 2026 08:25

git-nandor force-pushed the INSTUI-5031_better_multiversion_support_for_docs_v2 branch from 7e3bad3 to a04f8e7 Compare June 3, 2026 08:41

matyasf approved these changes Jun 3, 2026

View reviewed changes

Comment thread docs/guides/component-versioning.md Outdated

git-nandor force-pushed the INSTUI-5031_better_multiversion_support_for_docs_v2 branch from a04f8e7 to 9618859 Compare June 4, 2026 08:46

This comment was marked as resolved.

Sign in to view

git-nandor requested a review from ToMESSKa June 5, 2026 13:23

balzss reviewed Jun 9, 2026

View reviewed changes

git-nandor force-pushed the INSTUI-5031_better_multiversion_support_for_docs_v2 branch from 6770bb9 to c22a20d Compare June 10, 2026 13:10

git-nandor requested review from balzss and matyasf and removed request for HerrTopi June 11, 2026 13:23

git-nandor removed request for ToMESSKa and joyenjoyer June 11, 2026 13:30

git-nandor force-pushed the rework-documentation branch from 1c6da87 to 01baa9e Compare June 11, 2026 14:06

git-nandor added 6 commits June 11, 2026 17:20

docs(many): rework documentation

2cbd8e4

docs: improve multi-version docs behavior and routing and add new Com…

e02cf76

…ponent versioning guide page

docs: fix: remove latest version alert on legacy-theme-overrides doc …

dfc81a3

…page

docs: revert component selector labels, modify component-versioning g…

69d5725

…uide and bring up usage section on component pages

docs: fix new-theme-override example, fix relative hrefs

bf6e134

docs: clean up compileMarkdown's link handler to strip leading / and …

fdbbe53

…# before navigateTo so markdown links produce clean URLs

git-nandor force-pushed the INSTUI-5031_better_multiversion_support_for_docs_v2 branch from eb79668 to fdbbe53 Compare June 11, 2026 15:21

git-nandor requested a review from ToMESSKa June 11, 2026 15:32

git-nandor added 2 commits June 11, 2026 18:15

docs: fix withStyleForDocs JSDoc and remove duplicate @module and inc…

09fab81

…orrectly merged description

docs: move transpile-diff into contributing group

169cf9d

matyasf reviewed Jun 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: better multiversion support for docs v2#2568

docs: better multiversion support for docs v2#2568
git-nandor wants to merge 8 commits into
rework-documentationfrom
INSTUI-5031_better_multiversion_support_for_docs_v2

git-nandor commented May 27, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 27, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-06-12 08:32 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

github-actions Bot commented May 27, 2026 •

edited

Loading

Uh oh!

matyasf left a comment

Uh oh!

matyasf left a comment

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

balzss Jun 9, 2026

Uh oh!

git-nandor Jun 11, 2026

Uh oh!

balzss Jun 9, 2026

Uh oh!

balzss Jun 9, 2026

Uh oh!

git-nandor Jun 11, 2026

Uh oh!

matyasf left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		- `v2` (library `v11_7` and newer) supports themes built on the new token system. The legacy Canvas looks are preserved (re-implemented on the new engine) and two brand-new themes are added:

		- `legacyCanvas` — same visual style as the old `canvas`, but on the new engine

Conversation

git-nandor commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

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

Uh oh!

Built to branch gh-pages at 2026-06-12 08:32 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

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

Uh oh!

Visual regression report

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

balzss Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

git-nandor Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

balzss Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

balzss Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

git-nandor Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

git-nandor commented May 27, 2026 •

edited

Loading

github-actions Bot commented May 27, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-06-12 08:32 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

github-actions Bot commented May 27, 2026 •

edited

Loading