From f59ea30dc3988a9c54860a65b996c9d856267d66 Mon Sep 17 00:00:00 2001
From: Alex Szczuczko <aszczucz@redhat.com>
Date: Tue, 26 May 2026 14:16:45 -0600
Subject: [PATCH] Use appropriate cross-reference syntax in the UI
 Customization guide

Closes #49224

Signed-off-by: Alexander Schwartz <alexander.schwartz@ibm.com>
Signed-off-by: Alex Szczuczko <aszczucz@redhat.com>
---
 docs/guides/templates/links.adoc                | 1 +
 docs/guides/ui-customization/index.adoc         | 4 ++--
 docs/guides/ui-customization/quick-theme.adoc   | 2 +-
 docs/guides/ui-customization/themes-react.adoc  | 4 ++--
 docs/guides/ui-customization/welcome-theme.adoc | 4 ++--
 5 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/docs/guides/templates/links.adoc b/docs/guides/templates/links.adoc
index 197c694d356..b524d9f0b1f 100644
--- a/docs/guides/templates/links.adoc
+++ b/docs/guides/templates/links.adoc
@@ -4,3 +4,4 @@
 <#macro securingapps id anchor="">link:{links_securing-apps_${id}_url}<#if anchor != "">#${anchor}</#if>[{links_securing-apps_${id}_name}]</#macro>
 <#macro gettingstarted id anchor="">link:{links_getting-started_${id}_url}<#if anchor != "">#${anchor}</#if>[{links_getting-started_${id}_name}]</#macro>
 <#macro observability id anchor="">link:{links_observability_${id}_url}<#if anchor != "">#${anchor}</#if>[{links_observability_${id}_name}]</#macro>
+<#macro uicustomization id anchor="">link:{links_ui-customization_${id}_url}<#if anchor != "">#${anchor}</#if>[{links_ui-customization_${id}_name}]</#macro>
diff --git a/docs/guides/ui-customization/index.adoc b/docs/guides/ui-customization/index.adoc
index 493b087f5a8..fdcd2b7ebab 100644
--- a/docs/guides/ui-customization/index.adoc
+++ b/docs/guides/ui-customization/index.adoc
@@ -3,8 +3,8 @@
 include::../attributes.adoc[]
 
 <#list ctx.guides as guide>
-:links_ui_customization_${guide.id}_name: ${guide.title}
-:links_ui_customization_${guide.id}_url: #${guide.id}
+:links_ui-customization_${guide.id}_name: ${guide.title}
+:links_ui-customization_${guide.id}_url: #${guide.id}
 </#list>
 
 <#list ctx.guides as guide>
diff --git a/docs/guides/ui-customization/quick-theme.adoc b/docs/guides/ui-customization/quick-theme.adoc
index ea00fc66a96..7f595d388ae 100644
--- a/docs/guides/ui-customization/quick-theme.adoc
+++ b/docs/guides/ui-customization/quick-theme.adoc
@@ -59,5 +59,5 @@ jar xf quick-theme.jar
 === Trying out your new theme
 Your theme includes the images and colors you provided. They appear throughout the Account Console, Admin Console, and login page.
 
-Once your "Quick Theme" archive jar is deployed, you can fully test it using the procedures shown in the <<themes, Themes chapter>>.  Essentially, you just need to choose your new theme on the Realm settings --> Themes tab.
+Once your "Quick Theme" archive jar is deployed, you can fully test it using the procedures shown in the <@links.uicustomization id="themes"/> {section}. Essentially, you just need to choose your new theme on the Realm settings -> Themes tab.
 </@tmpl.guide>
diff --git a/docs/guides/ui-customization/themes-react.adoc b/docs/guides/ui-customization/themes-react.adoc
index c403e42dea5..b77932555ac 100644
--- a/docs/guides/ui-customization/themes-react.adoc
+++ b/docs/guides/ui-customization/themes-react.adoc
@@ -65,5 +65,5 @@ backend: {
 
 == Using the pages
 
-To see how to further integrate the pages, we recommend that you take a look at the output of the tool in the <<creating-your-own-console,Creating your own Console>> chapter.
-</@tmpl.guide>
\ No newline at end of file
+To see how to further integrate the pages, we recommend that you take a look at the output of the tool in the <@links.uicustomization id="creating-your-own-console"/> {section}.
+</@tmpl.guide>
diff --git a/docs/guides/ui-customization/welcome-theme.adoc b/docs/guides/ui-customization/welcome-theme.adoc
index 7226dc3f25e..7fca9ce3a82 100644
--- a/docs/guides/ui-customization/welcome-theme.adoc
+++ b/docs/guides/ui-customization/welcome-theme.adoc
@@ -12,9 +12,9 @@ By default, the welcome theme is only used during the initial setup to create th
 
 Since the welcome theme is not associated with a realm, it cannot be selected in the admin console like other themes.
 
-To change the welcome theme, create and deploy a new welcome theme as described in <<_creating-a-theme,Creating a theme>>.  Then, start the {project_name} server using the `spi-theme--welcome-theme` option.
+To change the welcome theme, create and deploy a new welcome theme as described in <@links.uicustomization id="themes" anchor="_creating-a-theme" />. Then, start the {project_name} server using the `spi-theme--welcome-theme` option.
 [source,bash]
 ----
 bin/kc.[sh|bat] start --spi-theme--welcome-theme=custom-theme
 ----
-</@tmpl.guide>
\ No newline at end of file
+</@tmpl.guide>