From 2230f2308f77282c50b0e7c9666e42f018d7e83a Mon Sep 17 00:00:00 2001 From: Erik Jan de Wit Date: Mon, 16 Nov 2026 10:23:40 +0100 Subject: [PATCH 1/2] Add PatternFly 6 custom theme migration guide Provide a dedicated migration guide for login, welcome, account, and admin custom themes in Keycloak 27, and link it from the upgrading and release notes. Closes #52348 Signed-off-by: Erik Jan de Wit --- .../release_notes/topics/27_0_0.adoc | 13 +- .../topics/changes/changes-27_0_0.adoc | 73 +++++ .../upgrading/topics/migrate_themes.adoc | 2 + docs/guides/attributes.adoc | 1 + .../migrating-themes-to-patternfly-6.adoc | 284 ++++++++++++++++++ docs/guides/templates/links.adoc | 1 + 6 files changed, 370 insertions(+), 4 deletions(-) create mode 100644 docs/guides/migration/migrating-themes-to-patternfly-6.adoc diff --git a/docs/documentation/release_notes/topics/27_0_0.adoc b/docs/documentation/release_notes/topics/27_0_0.adoc index 1d4c87b1755b..d39587f1063b 100644 --- a/docs/documentation/release_notes/topics/27_0_0.adoc +++ b/docs/documentation/release_notes/topics/27_0_0.adoc @@ -33,12 +33,17 @@ The `UPDATE_CREDENTIAL` events emitted by built-in required actions now carry th = Themes -== Login and welcome UI upgraded to PatternFly 6 +== User interfaces upgraded to PatternFly 6 -The built-in login theme is now `keycloak.v3`, based on PatternFly 6. The previous `keycloak.v2` login theme has been removed. -The built-in welcome theme also uses PatternFly 6. +{project_name} 27 upgrades the built-in login, welcome, Account Console, and Admin Console UIs to PatternFly 6: -Realms that explicitly used `keycloak.v2` are migrated to `keycloak.v3` during upgrade. If you maintain a custom login theme based on `keycloak.v2`, or a custom welcome theme based on PatternFly 5, see the link:{upgradingguide_link}[{upgradingguide_name}] for migration steps. +* Login theme is now `keycloak.v3` (replaces `keycloak.v2`). +* Welcome theme uses PatternFly 6 markup and styles. +* Account Console theme is now `keycloak.v4` (replaces `keycloak.v3`). +* Admin Console theme is now `keycloak.v3` (replaces `keycloak.v2`). + +Built-in realm themes are migrated automatically during upgrade. +If you maintain custom themes, see the link:{upgradingguide_link}[{upgradingguide_name}] and the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide]. == OID4VP verifier infers the DCQL query from mappers (experimental) diff --git a/docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc index 8e2a15242476..8b7107cd800b 100644 --- a/docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc @@ -71,6 +71,79 @@ node misc/scripts/migrate-login-theme-pf5-to-pf6.mjs --theme-path /path/to/your/ Run the script in dry-run mode first, review the generated report, and then rerun with `--apply` when ready. After migration, validate your customizations manually for light and dark mode, social provider buttons, and custom CSS overrides. +For a full walkthrough covering login, welcome, account, and admin custom themes, see the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide]. + +=== Account Console moved to `keycloak.v4` and PatternFly 6 +// https://github.com/keycloak/keycloak/issues/52344 + +The built-in Account Console is now the `keycloak.v4` theme, based on PatternFly 6. +The previous `keycloak.v3` Account Console theme and the `account:v3` feature value have been removed. + +For new realms, `keycloak.v4` is the default Account Console theme when the `account:v4` feature is enabled (the default). +Existing realms that explicitly use `keycloak`, `keycloak.v2`, or `keycloak.v3` as the account theme are migrated to `keycloak.v4` during upgrade. +Custom account themes are left unchanged. + +If you maintain a custom Account Console theme that extends or copies `keycloak.v3`, migrate it to PatternFly 6 before switching its parent to `keycloak.v4`. + +The helper script below migrates an Account UI *source checkout* (a directory whose `package.json` name is `@keycloak/keycloak-account-ui`), not an installed or inherited theme directory under `themes/`. +Pass the path of that source package with `--app-path`: + +[source,bash] +---- +node misc/scripts/migrate-account-ui-pf5-to-pf6.mjs --app-path /path/to/keycloak-account-ui +---- + +Run the script in dry-run mode first, review the generated report, and then rerun with `--apply` when ready. +For CSS-only custom themes that only override resources of `keycloak.v3`, update PatternFly 5 classes and CSS variables to PatternFly 6 manually; the helper does not process those theme directories. +If you explicitly enable `account:v3` (for example `--features=account:v3` or `KC_FEATURES=account:v3`), replace it with `account:v4`, or remove the entry because `account:v4` is enabled by default. +Servers that still request `account:v3` fail feature validation at startup. + +See also the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide]. + +=== Admin console migrated to PatternFly 6 +// https://github.com/keycloak/keycloak/issues/52343 + +The admin console has been upgraded to PatternFly 6 and the built-in admin theme has been renamed from `keycloak.v2` to `keycloak.v3`. +Realms that explicitly use the built-in admin theme are migrated automatically. +Custom admin themes must be updated manually. + +If your custom admin theme extends the built-in theme, update `theme.properties`: + +[source,properties] +---- +# Before +parent=keycloak.v2 + +# After +parent=keycloak.v3 +---- + +If your theme extends `rh-sso.v2`, change the parent to `rh-sso.v3` if available in your distribution, or extend `keycloak.v3` instead. + +If you explicitly enable or disable the admin console through startup features, replace `admin:v2` with `admin:v3` in `--features` or `--features-disabled`. +The `admin:v2` feature flag was removed with the PatternFly 6 admin console migration. + +The admin console now uses PatternFly 6 React components and design tokens. +Custom admin themes that bundle their own React components should: + +* Upgrade `@patternfly/react-core` and related packages to PatternFly 6. +* Replace deprecated PatternFly 5 APIs removed during the migration, including modal variants, `Chip` (use `Label`), and drag-and-drop helpers that depended on removed packages. +* Update CSS class prefixes from `pf-v5-*` to `pf-v6-*` and replace `--pf-v5-global--*` variables with the corresponding `--pf-t--global--*` tokens where applicable. + +To assist with migrating an Admin UI source checkout, use: + +[source,bash] +---- +node misc/scripts/migrate-admin-ui-pf5-to-pf6.mjs --app-path /path/to/keycloak-admin-ui +---- + +Run the script in dry-run mode first, review the generated report, and then rerun with `--apply` when ready. + +The built-in quick-theme generator now produces admin themes with `parent=keycloak.v3`. +Download a new quick theme after upgrading if you previously generated one for `keycloak.v2`. + +See also the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide]. + === OIDC identity providers accept a single issuer // https://github.com/keycloak/keycloak/issues/54458 diff --git a/docs/documentation/upgrading/topics/migrate_themes.adoc b/docs/documentation/upgrading/topics/migrate_themes.adoc index 7d28d3e84bac..8c57491a1a6c 100644 --- a/docs/documentation/upgrading/topics/migrate_themes.adoc +++ b/docs/documentation/upgrading/topics/migrate_themes.adoc @@ -4,6 +4,8 @@ If you created custom themes, those themes must be migrated to the new server. Also, any changes to the built-in themes might need to be reflected in your custom themes, depending on which aspects you customized. +For the PatternFly 6 upgrade in {project_name} 27 (login, welcome, Account Console, and Admin Console), see the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide] in addition to the version-specific notes in <>. + .Procedure . Copy your custom themes from the old server `themes` directory to the new server `themes` directory. diff --git a/docs/guides/attributes.adoc b/docs/guides/attributes.adoc index b040c2f32492..239f6065ec74 100644 --- a/docs/guides/attributes.adoc +++ b/docs/guides/attributes.adoc @@ -36,6 +36,7 @@ :quickstartRepo_dir: keycloak-quickstarts :securing_apps_link: https://www.keycloak.org/guides#securing-apps :upgrading_guide_link: {project_doc_base_url}/upgrading/ +:upgradingguide_name: Upgrading Guide :migrate_db: {upgrading_guide_link}#_migrate_db :developerguide_userstoragespi_link: {developerguide_link}#_user-storage-spi :developerguide_userstoragespi_name: User Storage SPI diff --git a/docs/guides/migration/migrating-themes-to-patternfly-6.adoc b/docs/guides/migration/migrating-themes-to-patternfly-6.adoc new file mode 100644 index 000000000000..0024f15b7862 --- /dev/null +++ b/docs/guides/migration/migrating-themes-to-patternfly-6.adoc @@ -0,0 +1,284 @@ +<#import "/templates/guide.adoc" as tmpl> +<#import "/templates/links.adoc" as links> + +<@tmpl.guide +title="Migrating custom themes to PatternFly 6" +priority=10 +summary="Migrate custom login, welcome, account, and admin themes from PatternFly 5 to PatternFly 6 for {project_name} 27."> + +{project_name} 27 upgrades its built-in user interfaces from PatternFly 5 to PatternFly 6. +Custom themes that extend or copy those UIs need a corresponding migration before or during the upgrade. + +This guide covers what changes for each theme type, which helpers exist, and how to validate the result. +For the short per-release summary, see the link:{upgrading_guide_link}[{upgradingguide_name}]. +For general theme structure, see <@links.uicustomization id="themes" />. + +== What changed in {project_name} 27 + +[%header,cols="1,2,2"] +|=== +| Theme type | Built-in theme | PatternFly version + +| Login +| `keycloak.v3` (replaces `keycloak.v2`) +| PatternFly 6 + +| Welcome +| `keycloak` welcome theme +| PatternFly 6 + +| Account Console +| `keycloak.v4` (replaces `keycloak.v3`) +| PatternFly 6 + +| Admin Console +| `keycloak.v3` (replaces `keycloak.v2`) +| PatternFly 6 +|=== + +Built-in realm themes are migrated automatically when you upgrade. +Custom themes are left unchanged and must be updated by you. + +Common PatternFly 5 to 6 changes that affect custom themes: + +* CSS class prefixes move from `pf-v5-*` to `pf-v6-*`. +* Global CSS variables move from `--pf-v5-global--*` toward PatternFly 6 design tokens (`--pf-t--global--*` and related). +* Vendor stylesheet paths move from `vendor/patternfly-v5/` to `vendor/patternfly-v6/`. +* Some React component APIs used by the Account and Admin consoles were removed or renamed in PatternFly 6. + +Upstream PatternFly references: + +* https://www.patternfly.org/get-started/upgrade/[PatternFly upgrade overview] +* https://github.com/patternfly/pf-codemods[PatternFly codemods] +* https://github.com/patternfly/patternfly/blob/main/UPGRADE-GUIDE.md[PatternFly CSS upgrade guide] + +== Before you start + +. Inventory every custom theme under `themes/` (and any separately packaged theme JARs). +. Note each theme's `parent=` value and whether it copies templates, CSS, or only messages. +. Prefer extending built-in themes and overriding as little as possible. + Themes that only override messages or a few CSS rules are cheapest to migrate. +. Keep a copy of the old theme until you have validated login, account, and admin flows on {project_name} 27. +. {project_name} 26.8.x remains supported for a period after 27.0 so you can migrate themes before cutting over production. + +== Login themes + +Login is the FreeMarker-based experience (`login` theme type). +In {project_name} 27 the default built-in theme is `keycloak.v3`. + +=== Automatic realm migration + +* New realms default to `keycloak.v3`. +* Existing realms that used `keycloak.v2` are migrated to `keycloak.v3`. +* Realms that still used the removed Login v1 theme (`keycloak`) are also migrated to `keycloak.v3`. +* Custom login theme names are not rewritten. + +=== Feature flags + +`login:v2` and `login:v1` are removed. +If you still set `--features=login:v2` or `KC_FEATURES=login:v2`, replace it with `login:v3` or remove the entry (`login:v3` is the default). +Servers that still request `login:v2` fail feature validation at startup. + +=== Prefer the Base theme macros + +Login pages and macros live in the Base login theme. +`keycloak.v3` supplies PatternFly 6 styling through `theme.properties` and resources without duplicating full page templates. + +When migrating a custom login theme: + +. Set `parent=keycloak.v3` (or `parent=base` if you own the full markup). +. Drop copied page templates such as `login.ftl` or `register.ftl` when you only need styling changes. +. Override individual Base macros or a few `kc*` class properties instead of whole pages. +. Update any `styles` / `stylesCommon` entries that still point at `vendor/patternfly-v5/`. + +=== Helper script for login themes + +{project_name} provides a migration script that runs PatternFly codemods against a custom login theme and rewrites common `theme.properties` values. + +[source,bash] +---- +# Dry-run (default): writes a report, does not modify the theme +node misc/scripts/migrate-login-theme-pf5-to-pf6.mjs \ + --theme-path /path/to/your-theme + +# Apply after reviewing the report +node misc/scripts/migrate-login-theme-pf5-to-pf6.mjs \ + --theme-path /path/to/your-theme \ + --apply \ + --fail-on-unresolved +---- + +`--theme-path` may point at the theme root or at the `login` directory. +When the theme root has a sibling `common/` directory used through `import=common/...`, that directory is migrated as well. + +The script: + +* Runs `@patternfly/pf-codemods` (`tokens-update`), `@patternfly/css-vars-updater`, and `@patternfly/class-name-updater` on a staged copy. +* Rewrites `vendor/patternfly-v5/` to `vendor/patternfly-v6/`, `pf-v5-theme-dark` to `pf-v6-theme-dark`, and `parent=keycloak.v2` (or `rh-sso.v2`) to `parent=keycloak.v3`. +* Writes markdown and JSON reports under `misc/scripts/reports/` (or `--report-dir`). +* Creates a backup under `misc/scripts/reports/backups/` when `--apply` succeeds. + +Always review the report for residual `pf-v5-*` markers and temporary PatternFly tokens, then validate pages manually. + +=== Manual login checklist + +Even after a successful script run, verify: + +* Username/password, registration, and reset-credentials pages in light and dark mode. +* Social identity-provider buttons and icons (`kcLogoIdP-*` properties). +* Error, info, and required-action pages you customized. +* Any custom CSS that targeted `pf-v5-*` layout utilities or global variables. +* Locales you maintain; compare message keys with the Base / `keycloak.v3` bundles. + +== Welcome themes + +The built-in welcome theme uses PatternFly 6 markup and `vendor/patternfly-v6/` stylesheets. + +If your custom welcome theme copied PatternFly 5 classes or stylesheets: + +. Update `theme.properties` so `stylesCommon` (or equivalent) loads PatternFly 6 vendor CSS. +. Replace `pf-v5-*` classes in `index.ftl` and custom CSS with PatternFly 6 equivalents. +. Re-test first-boot admin creation and the post-bootstrap redirect to the Admin Console. + +There is no dedicated welcome helper script; reuse the PatternFly class-name and CSS-variable updaters on the welcome directory if the theme is large. + +== Account Console themes + +The Account Console is a React application packaged as an account theme. +The built-in Account Console is now `keycloak.v4`, based on PatternFly 6. +The previous `keycloak.v3` Account Console theme and the `account:v3` feature value have been removed. + +=== Automatic realm migration + +* For new realms, `keycloak.v4` is the default Account Console theme when the `account:v4` feature is enabled (the default). +* Existing realms that explicitly use `keycloak`, `keycloak.v2`, or `keycloak.v3` as the account theme are migrated to `keycloak.v4` during upgrade. +* Custom account theme names are left unchanged; update their `parent=` yourself. + +=== Feature flags + +If you explicitly enable `account:v3` (for example `--features=account:v3` or `KC_FEATURES=account:v3`), replace it with `account:v4`, or remove the entry because `account:v4` is enabled by default. +Servers that still request `account:v3` fail feature validation at startup. + +=== Custom Account UI source packages + +If you maintain a fork of `@keycloak/keycloak-account-ui` (or an equivalent source package that reuses those components): + +. Upgrade `@patternfly/react-core` and related PatternFly packages to PatternFly 6. +. Run the Account helper script (or PatternFly's React and CSS codemods) against that source package. +. Replace removed PatternFly 5 React APIs and `pf-v5-*` class names. +. Point the account theme `parent=` at `keycloak.v4`. + +The helper script migrates an Account UI *source checkout* whose `package.json` name is `@keycloak/keycloak-account-ui`. +It does not rewrite installed or inherited theme directories under `themes/`. + +[source,bash] +---- +# Dry-run (default) +node misc/scripts/migrate-account-ui-pf5-to-pf6.mjs \ + --app-path /path/to/keycloak-account-ui + +# Apply after reviewing the report +node misc/scripts/migrate-account-ui-pf5-to-pf6.mjs \ + --app-path /path/to/keycloak-account-ui \ + --apply \ + --fail-on-unresolved +---- + +The script runs `@patternfly/pf-codemods` (`--v6`), `@patternfly/css-vars-updater`, and `@patternfly/class-name-updater` on a staged copy, writes reports under `misc/scripts/reports/`, and creates a backup when `--apply` succeeds. + +=== CSS-only account themes + +If your custom account theme only overrides resources of `keycloak.v3`: + +. Change `parent=` to `keycloak.v4`. +. Update PatternFly 5 classes and CSS variables to PatternFly 6 manually; the helper script does not process those theme directories. +. Re-test the Account Console pages you styled. + +== Admin Console themes + +The Admin Console is a React application. +It has been upgraded to PatternFly 6, and the built-in admin theme has been renamed from `keycloak.v2` to `keycloak.v3`. +Realms that explicitly use the built-in admin theme are migrated automatically. +Custom admin themes must be updated manually. + +=== Feature flags + +If you explicitly enable or disable the admin console through startup features, replace `admin:v2` with `admin:v3` in `--features` or `--features-disabled`. +The `admin:v2` feature flag was removed with the PatternFly 6 admin console migration. + +=== Rename the admin theme parent + +If your custom admin theme extends the built-in theme, update `theme.properties`: + +[source,properties] +---- +# Before +parent=keycloak.v2 + +# After +parent=keycloak.v3 +---- + +If your theme extends `rh-sso.v2`, change the parent to `rh-sso.v3` if available in your distribution, or extend `keycloak.v3` instead. + +=== Custom Admin UI source packages + +If you maintain a fork of the Admin UI (or bundle your own PatternFly React components for admin): + +. Upgrade `@patternfly/react-core` and related packages to PatternFly 6. +. Replace deprecated PatternFly 5 APIs removed during the migration, including modal variants, `Chip` (use `Label`), and drag-and-drop helpers that depended on removed packages. +. Update CSS class prefixes from `pf-v5-*` to `pf-v6-*` and replace `--pf-v5-global--*` variables with the corresponding `--pf-t--global--*` tokens where applicable. +. Run the Admin helper script against your Admin UI source checkout. + +[source,bash] +---- +# Dry-run (default); defaults to js/apps/admin-ui +node misc/scripts/migrate-admin-ui-pf5-to-pf6.mjs \ + --app-path /path/to/keycloak-admin-ui + +# Apply after reviewing the report +node misc/scripts/migrate-admin-ui-pf5-to-pf6.mjs \ + --app-path /path/to/keycloak-admin-ui \ + --apply \ + --fail-on-unresolved +---- + +The script runs the same PatternFly codemod pipeline as the Account helper on a staged copy of the Admin UI app, writes reports under `misc/scripts/reports/`, and creates a backup when `--apply` succeeds. + +=== Quick theme downloads + +The built-in quick-theme generator produces admin themes with `parent=keycloak.v3`. +Download a new quick theme after upgrading if you previously generated one for `keycloak.v2`. + +== Themes built with Keycloakify + +If you generate themes with https://www.keycloakify.dev/[Keycloakify], follow Keycloakify's PatternFly 6 / {project_name} 27 upgrade guidance for that toolchain, then re-validate the generated themes against a {project_name} 27 server. +Use a Keycloakify release that targets `keycloak.v3` for login, `keycloak.v4` for account, and `keycloak.v3` for admin. + +== Validation checklist + +After migrating each custom theme: + +. Start {project_name} 27 with theme caching disabled while iterating: ++ +[source,bash] +---- +bin/kc.[sh|bat] start-dev \ + --spi-theme--static-max-age=-1 \ + --spi-theme--cache-themes=false \ + --spi-theme--cache-templates=false +---- +. Confirm the realm (or `spi-theme--welcome-theme`) selects your migrated theme. +. Walk the critical paths for that theme type (login/register/reset, account profile/applications, admin realm/client screens you customized). +. Check light and dark mode where applicable. +. Search the theme for leftover `pf-v5-`, `patternfly-v5`, and old parents (`keycloak.v2` for login/admin, `keycloak.v3` for account). +. Re-test any customized translations. + +== Related documentation + +* link:{upgrading_guide_link}[{upgradingguide_name}] — breaking-change notes for {project_name} 27 +* <@links.uicustomization id="themes" /> — creating and extending themes +* <@links.uicustomization id="welcome-theme" /> — welcome theme selection +* `misc/scripts/README.md` — migration script options + + diff --git a/docs/guides/templates/links.adoc b/docs/guides/templates/links.adoc index 47c68b569e58..6c87e8abc37d 100644 --- a/docs/guides/templates/links.adoc +++ b/docs/guides/templates/links.adoc @@ -5,4 +5,5 @@ <#macro gettingstarted id anchor="">link:{links_getting-started_${id}_url}<#if anchor != "">#${anchor}[{links_getting-started_${id}_name}] <#macro observability id anchor="">link:{links_observability_${id}_url}<#if anchor != "">#${anchor}[{links_observability_${id}_name}] <#macro uicustomization id anchor="">link:{links_ui-customization_${id}_url}<#if anchor != "">#${anchor}[{links_ui-customization_${id}_name}] +<#macro migration id anchor="">link:{links_migration_${id}_url}<#if anchor != "">#${anchor}[{links_migration_${id}_name}] <#macro adminapi id anchor="">link:{links_admin-api_${id}_url}<#if anchor != "">#${anchor}[{links_admin-api_${id}_name}] From d4705d335698394576fa8ce4325eaa722f284216 Mon Sep 17 00:00:00 2001 From: Erik Jan de Wit Date: Mon, 16 Nov 2026 10:43:22 +0100 Subject: [PATCH 2/2] Fix external link check for PatternFly 6 migration guide Point upgrading and release notes at the published Migration guides section instead of the not-yet-published direct guide URL. Signed-off-by: Erik Jan de Wit --- docs/documentation/release_notes/topics/27_0_0.adoc | 2 +- .../upgrading/topics/changes/changes-27_0_0.adoc | 6 +++--- docs/documentation/upgrading/topics/migrate_themes.adoc | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/documentation/release_notes/topics/27_0_0.adoc b/docs/documentation/release_notes/topics/27_0_0.adoc index d39587f1063b..9e73664db36b 100644 --- a/docs/documentation/release_notes/topics/27_0_0.adoc +++ b/docs/documentation/release_notes/topics/27_0_0.adoc @@ -43,7 +43,7 @@ The `UPDATE_CREDENTIAL` events emitted by built-in required actions now carry th * Admin Console theme is now `keycloak.v3` (replaces `keycloak.v2`). Built-in realm themes are migrated automatically during upgrade. -If you maintain custom themes, see the link:{upgradingguide_link}[{upgradingguide_name}] and the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide]. +If you maintain custom themes, see the link:{upgradingguide_link}[{upgradingguide_name}] and *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides]. == OID4VP verifier infers the DCQL query from mappers (experimental) diff --git a/docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc index 8b7107cd800b..0321d33e0b8e 100644 --- a/docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc @@ -71,7 +71,7 @@ node misc/scripts/migrate-login-theme-pf5-to-pf6.mjs --theme-path /path/to/your/ Run the script in dry-run mode first, review the generated report, and then rerun with `--apply` when ready. After migration, validate your customizations manually for light and dark mode, social provider buttons, and custom CSS overrides. -For a full walkthrough covering login, welcome, account, and admin custom themes, see the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide]. +For a full walkthrough covering login, welcome, account, and admin custom themes, see *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides]. === Account Console moved to `keycloak.v4` and PatternFly 6 // https://github.com/keycloak/keycloak/issues/52344 @@ -98,7 +98,7 @@ For CSS-only custom themes that only override resources of `keycloak.v3`, update If you explicitly enable `account:v3` (for example `--features=account:v3` or `KC_FEATURES=account:v3`), replace it with `account:v4`, or remove the entry because `account:v4` is enabled by default. Servers that still request `account:v3` fail feature validation at startup. -See also the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide]. +See also *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides]. === Admin console migrated to PatternFly 6 // https://github.com/keycloak/keycloak/issues/52343 @@ -142,7 +142,7 @@ Run the script in dry-run mode first, review the generated report, and then reru The built-in quick-theme generator now produces admin themes with `parent=keycloak.v3`. Download a new quick theme after upgrading if you previously generated one for `keycloak.v2`. -See also the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide]. +See also *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides]. === OIDC identity providers accept a single issuer // https://github.com/keycloak/keycloak/issues/54458 diff --git a/docs/documentation/upgrading/topics/migrate_themes.adoc b/docs/documentation/upgrading/topics/migrate_themes.adoc index 8c57491a1a6c..e8511ca41ab0 100644 --- a/docs/documentation/upgrading/topics/migrate_themes.adoc +++ b/docs/documentation/upgrading/topics/migrate_themes.adoc @@ -4,7 +4,7 @@ If you created custom themes, those themes must be migrated to the new server. Also, any changes to the built-in themes might need to be reflected in your custom themes, depending on which aspects you customized. -For the PatternFly 6 upgrade in {project_name} 27 (login, welcome, Account Console, and Admin Console), see the https://www.keycloak.org/migration/migrating-themes-to-patternfly-6[PatternFly 6 theme migration guide] in addition to the version-specific notes in <>. +For the PatternFly 6 upgrade in {project_name} 27 (login, welcome, Account Console, and Admin Console), see *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides] in addition to the version-specific notes in <>. .Procedure