RHIDP-8202 DITA compatible links in concept and references modules (#1374)

themr0c · jmagak · web-flow · commit d3e365fcf189 · 2025-09-15T09:42:24.000+02:00
Co-authored-by: Judith Magak &lt;124673476+jmagak@users.noreply.github.com&gt;
diff --git a/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc b/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc
@@ -30,5 +30,5 @@ include::../modules/dynamic-plugins/proc-load-plugin-tgz-file.adoc[leveloffset=+
 include::../modules/dynamic-plugins/proc-load-plugin-js-package.adoc[leveloffset=+2]
 
 //example third-party plugin installation
-include::../modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc[leveloffset=+2]
+include::../modules/dynamic-plugins/proc-example-third-party-plugin-installation.adoc[leveloffset=+2]
 
diff --git a/modules/about/ref-customer-support-info.adoc b/modules/about/ref-customer-support-info.adoc
@@ -3,9 +3,13 @@
 [id="ref-customer-support-info_{context}"]
 = {product} support
 
-If you experience difficulty with a procedure described in this documentation, visit the https://access.redhat.com[Red Hat Customer Portal]. You can use the Red Hat Customer Portal for the following purposes:
+If you experience difficulty with a procedure described in this documentation, visit the {company-name} Customer Portal.
+You can use the {company-name} Customer Portal for the following purposes:
 
 * To search or browse through the Red Hat Knowledgebase of technical support articles about Red Hat products.
-* To create a https://access.redhat.com/support/cases/#/case/new/get-support?caseCreate=true[support case] for {company-name} Global Support Services (GSS). For support case creation, select *{product}* as the product and select the appropriate product version.
-* For detailed information about supported platforms and life cycle details, see link:https://access.redhat.com/support/policy/updates/developerhub[{product} Life Cycle].
+* To create a support case for {company-name} Global Support Services (GSS), select *{product}* as the product and select the appropriate product version.
 
+.Additional resources
+* link:https://access.redhat.com[Red Hat Customer Portal]
+* link:https://access.redhat.com/support/cases/#/case/new/get-support?caseCreate=true[Create a support case for {company-name} Global Support Services (GSS)]
+* link:https://access.redhat.com/support/policy/updates/developerhub[{product} Life Cycle]
diff --git a/modules/about/ref-supported-platforms.adoc b/modules/about/ref-supported-platforms.adoc
@@ -3,5 +3,7 @@
 [id="supported-platforms_{context}"]
 = Supported platforms
 
-You can find the supported platforms and life cycle dates for both current and past versions of {product} on the link:https://access.redhat.com/support/policy/updates/developerhub[Life Cycle page].
+You can find the supported platforms and life cycle dates for both current and past versions of {product} on the Life Cycle page.
 
+.Additional resources
+* link:https://access.redhat.com/support/policy/updates/developerhub[Life Cycle page]
diff --git a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc
@@ -4,14 +4,14 @@
 
 This module provides an overview of how authentication and user provisioning function within {product}.
 Learn about the process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step.
-Understanding this process is essential for successfully {configuring-book-link}[configuring your {product-short} instance], {authorization-book-link}[securing access through authorization], and enabling features that rely on synchronized user and group data.
+Understanding this process is essential for successfully configuring your {product-short} instance, securing access through authorization, and enabling features that rely on synchronized user and group data.
 
 To fully enable catalog features, provision user and group data from the Identity Provider to the {product-short} software catalog.
 Catalog provider plugins handle this task asynchronously.
 These plugins query the Identity Provider (IdP) for relevant user and group information, and create or update corresponding entities in the {product-short} catalog.
 Scheduled provisioning ensures that the catalog accurately reflects the users and groups in your organization.
 
-When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as xref:assembly-authenticating-with-rhbk[{rhbk-brand-name} ({rhbk})], xref:enabling-user-authentication-with-github[GitHub], or xref:enabling-user-authentication-with-microsoft-azure[{azure-brand-name}].
+When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as {rhbk-brand-name} ({rhbk}), GitHub, or {azure-brand-name}.
 This external IdP is responsible for authenticating the user.
 
 On successful authentication, the {product-short} authentication plugin, configured in your `{my-app-config-file}` file, processes the response from the IdP, resolves the identity in the {product-short} software catalog, and establishes a user session within {product-short}.
@@ -27,7 +27,7 @@ Without this provisioning step, features like displaying who owns a component in
 ====
 To explore {product-short} features in a non-production environment, you can:
 
-* To use {product-short} without external IdP, xref:authenticating-with-the-guest-user_{context}[enable the guest user] to skip configuring authentication and authorization, log in as the guest user, and access all {product-short} features.
+* To use {product-short} without external IdP, enable the guest user to skip configuring authentication and authorization, log in as the guest user, and access all {product-short} features.
 
 * To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option. This setting bypasses the check requiring a user to be in the catalog but still enforces authentication.
 ====
diff --git a/modules/authorization/con-rbac-conditional-policies-rhdh.adoc b/modules/authorization/con-rbac-conditional-policies-rhdh.adoc
@@ -21,12 +21,10 @@ A condition in {product-short} is a simple condition with a rule and parameters.
 
 Conditional object::
 +
---
 The plugin specifies the parameters supported for conditions. You can access the conditional object schema from the RBAC API endpoint to understand how to construct a conditional JSON object, which is then used by the RBAC backend plugin API.
-
++
 A conditional object contains the following parameters:
-
-.Conditional object parameters
++
 [cols="30%,45%,25%", frame="all", options="header"]
 |===
 |Parameter
@@ -58,20 +56,17 @@ A conditional object contains the following parameters:
 |Condition JSON with parameters or array parameters joined by criteria
 
 |===
---
 
 Conditional policy aliases::
 +
---
 The RBAC backend plugin (`backstage-plugin-rbac-backend`) supports the use of aliases in conditional policy rule parameters. The conditional policy aliases are dynamically replaced with the corresponding values during policy evaluation. Each alias in conditional policy is prefixed with a `$` sign indicating its special function.
-
++
 The supported conditional aliases include:
-
++
 * `$currentUser`: This alias is replaced with the user entity reference for the user who requests access to the resource. For example, if user Tom from the default namespace requests access, `$currentUser` becomes `user:default/tom`.
 +
---
-
-.Example conditional policy object with `$currentUser` alias
+Example conditional policy object with `$currentUser` alias:
++
 [source,json]
 ----
 {
@@ -89,12 +84,11 @@ The supported conditional aliases include:
   }
 }
 ----
---
 
 * `$ownerRefs`: This alias is replaced with ownership references, usually as an array that includes the user entity reference and the user's parent group entity reference. For example, for user Tom from team-a, `$ownerRefs` becomes `['user:default/tom', 'group:default/team-a']`.
 +
---
-.Example conditional policy object with `$ownerRefs` alias
+Example conditional policy object with `$ownerRefs` alias:
++
 [source,json]
 ----
 {
@@ -112,8 +106,3 @@ The supported conditional aliases include:
   }
 }
 ----
---
---
-
-
-
diff --git a/modules/authorization/ref-rbac-conditional-policy-definition.adoc b/modules/authorization/ref-rbac-conditional-policy-definition.adoc
@@ -341,7 +341,8 @@ In the previous example, the annotation `keycloak.org/realm` requires the value
 
 The previous example of Quay plugin prevents the role `role:default/developer` from using the Quay scaffolder action. Note that `permissionMapping` contains `use`, signifying that `scaffolder-action` resource type permission does not have a permission policy.
 
-For more information about permissions in {product}, see xref:ref-rbac-permission-policies_{context}[].
+.Additional resources
+* xref:ref-rbac-permission-policies_{context}[]
 
 
 
diff --git a/modules/customizing-the-appearance/ref-customize-rhdh-custom-components.adoc b/modules/customizing-the-appearance/ref-customize-rhdh-custom-components.adoc
@@ -10,7 +10,7 @@ There are two component variants that you can use to customize various component
 
 In addition to assigning a component variant to each parameter in the light or dark theme mode configurations, you can toggle the `rippleEffect` `on` or `off`.
 
-The following code shows the options that you can use in the {configuring-book-link}[`{my-app-config-file}` file] to configure the theme components for your {product-short} instance:
+The following code shows the options that you can use in the `{my-app-config-file}` file to configure the theme components for your {product-short} instance:
 
 [source,yaml]
 ----
diff --git a/modules/developer-lightspeed/con-about-bring-your-own-model.adoc b/modules/developer-lightspeed/con-about-bring-your-own-model.adoc
@@ -7,7 +7,10 @@
 //Add the cross reference to "Bring your own model"
 The only technical requirements for inference services are:
 
-* The service must conform to the link:https://github.com/openai/openai-openapi/tree/manual_spec[OpenAI API specification].
+* The service must conform to the OpenAI API specification.
 * The service must be configured correctly following the installation and configuration instructions.
 // Add the cross-reference to "Installation and configuraiton" after the docs are published
 There are many commercial and open source inference services that support the OpenAI API specification for chat completions. The cost, performance, and security of these services can differ and it is up to you to choose, through evaluation and testing, the inference service that best meets your company's needs.
+
+.Additional resources
+* link:https://github.com/openai/openai-openapi/tree/manual_spec[OpenAI API specification]
diff --git a/modules/developer-lightspeed/con-about-developer-lightspeed.adoc b/modules/developer-lightspeed/con-about-developer-lightspeed.adoc
@@ -11,6 +11,10 @@ This early access program enables customers to share feedback on the user experi
 
 {ls-short} provides a natural language interface within the {product-very-short} console, helping you easily find information about the product, understand its features, and get answers to your questions.
 
-You can experience {ls-short} Developer Preview by installing the Developer Lightspeed for {product} plugin within an existing {product-very-short} instance. Alternatively, if you prefer to test it locally first, you can try {ls-short} using link:https://github.com/redhat-developer/rhdh-local/blob/main/README.md[{product-local-very-short}].
+You can experience {ls-short} Developer Preview by installing the Developer Lightspeed for {product} plugin within an existing {product-very-short} instance.
+Alternatively, if you prefer to test it locally first, you can try {ls-short} using {product-local-very-short}.
 
 image::rhdh-plugins-reference/developer-lightspeed.png[]
+
+.Additional resources
+* link:https://github.com/redhat-developer/rhdh-local/blob/main/README.md[{product-local-very-short}]
diff --git a/modules/developer-lightspeed/con-ollama.adoc b/modules/developer-lightspeed/con-ollama.adoc
@@ -3,6 +3,10 @@
 [id="con-ollama_{context}"]
 = Ollama
 
-link:https://ollama.com[Ollama] is a powerful and easy-to-use open-source project that simplifies the process of running large language models (LLMs) locally on your computer. It provides a simple command-line interface for downloading, managing, and running a wide variety of open-source models, such as Llama 3, Mistral, and many others, all without requiring a dedicated server or cloud service. By abstracting away the complex setup and dependencies, Ollama makes it accessible for developers, researchers, and enthusiasts to experiment with, build on, and integrate state-of-the-art LLMs into their applications directly from their personal machines.
+Ollama is a powerful and easy-to-use open-source project that simplifies the process of running large language models (LLMs) locally on your computer. It provides a simple command-line interface for downloading, managing, and running a wide variety of open-source models, such as Llama 3, Mistral, and many others, all without requiring a dedicated server or cloud service. By abstracting away the complex setup and dependencies, Ollama makes it accessible for developers, researchers, and enthusiasts to experiment with, build on, and integrate state-of-the-art LLMs into their applications directly from their personal machines.
 
-The open source Ollama server link:https://hub.docker.com/r/ollama/ollama[in container form] provides a convenient local testbed for LLM models that is very accessible and easily controlled.
+The open source Ollama server in container form provides a convenient local testbed for LLM models that is very accessible and easily controlled.
+
+.Additional resources
+* link:https://ollama.com[Ollama]
+* link:https://hub.docker.com/r/ollama/ollama[Ollama server container]
diff --git a/modules/developer-lightspeed/con-openshift-ai.adoc b/modules/developer-lightspeed/con-openshift-ai.adoc
@@ -3,8 +3,12 @@
 [id="con-openshift-ai_{context}"]
 = {rhoai-brand-name}
 
-link:https://www.redhat.com/en/products/ai/openshift-ai[{rhoai-brand-name}] is a platform for managing the complete lifecycle of predictive and generative AI (gen AI) models, at scale, and across hybrid cloud environments. Built using open source technologies, OpenShift AI provides trusted, operationally consistent capabilities for teams to experiment, serve models, and deliver innovative applications.
+{rhoai-brand-name} is a platform for managing the complete lifecycle of predictive and generative AI (gen AI) models, at scale, and across hybrid cloud environments. Built using open source technologies, OpenShift AI provides trusted, operationally consistent capabilities for teams to experiment, serve models, and deliver innovative applications.
 
 {rhoai-brand-name} enables data acquisition and preparation, model training and fine-tuning, model serving and model monitoring, and hardware acceleration. With an open ecosystem of hardware and software partners, OpenShift AI delivers the flexibility you need for your specific use cases.
 
-To use {rhoai-brand-name} with {ls-short}, you must deploy an LLM on the {rhoai-brand-name} single-model serving platform using the xref:con-vllm_{context}[Virtual Large Language Model (vLLM)].
+To use {rhoai-brand-name} with {ls-short}, you must deploy an LLM on the {rhoai-brand-name} single-model serving platform using the Virtual Large Language Model (vLLM).
+
+.Additional resources
+* link:https://www.redhat.com/en/products/ai/openshift-ai[{rhoai-brand-name}]
+* xref:con-vllm_{context}[Virtual Large Language Model (vLLM)]
diff --git a/modules/developer-lightspeed/con-supported-architecture.adoc b/modules/developer-lightspeed/con-supported-architecture.adoc
@@ -4,9 +4,12 @@
 = Supported architecture for {ls-brand-name}
 
 {ls-short} is available as a plugin on all platforms that host {product-very-short}, and it requires the use of {rcs-name} ({rcs-short}) as a sidecar container.
-For more information on the different available platforms to install {product-very-short}, see {install-category-link}[Install].
+
 
 [NOTE]
 ====
 Currently, the provided {rcs-short} image is built for x86 platforms. To use other platforms (for example, arm64), ensure that you enable emulation.
 ====
+
+.Additional resources
+* link:https://access.redhat.com/support/policy/updates/developerhub[{product} Life Cycle and supported platforms]
diff --git a/modules/dynamic-plugins/con-ansible-plugin-admin.adoc b/modules/dynamic-plugins/con-ansible-plugin-admin.adoc
@@ -5,6 +5,7 @@
 Ansible plug-ins for {product} deliver an Ansible-specific portal experience with curated learning paths,
 push-button content creation, integrated development tools, and other opinionated resources.
 
-To install and configure the Ansible plugins, see
-{ansible-automation-platform-docs-link}/html-single/installing_ansible_plug-ins_for_red_hat_developer_hub/index[_Installing Ansible plug-ins for {product}_].
+.Additional resources
+
+* {ansible-automation-platform-docs-link}/html-single/installing_ansible_plug-ins_for_red_hat_developer_hub/index[_Installing Ansible plug-ins for {product}_]
 
diff --git a/modules/dynamic-plugins/con-ansible-plugin-user.adoc b/modules/dynamic-plugins/con-ansible-plugin-user.adoc
@@ -10,12 +10,10 @@ push-button content creation, integrated development tools, and other opinionate
 The Ansible plug-ins are a Technology Preview feature only.
 
 Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
-
-For more information on Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Scope].
-
-Additional detail on how Red Hat provides support for bundled community dynamic plugins is available on the https://access.redhat.com/policy/developerhub-support-policy[Red Hat Developer Support Policy] page.
 ====
 
-To use the Ansible plugins, see
-{ansible-automation-platform-docs-link}/html-single/using_ansible_plug-ins_for_red_hat_developer_hub/index[_Using Ansible plug-ins for {product}_].
+.Additonal resources
+* link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Scope]
+* link:https://access.redhat.com/policy/developerhub-support-policy[Red Hat Developer Support Policy]
+* {ansible-automation-platform-docs-link}/html-single/using_ansible_plug-ins_for_red_hat_developer_hub/index[_Using Ansible plug-ins for {product}_]
 
diff --git a/modules/dynamic-plugins/con-ansible-plugin.adoc b/modules/dynamic-plugins/con-ansible-plugin.adoc
@@ -11,18 +11,13 @@ The Ansible plug-ins are a Technology Preview feature only.
 
 Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
 
-For more information on Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Scope].
 
-Additional detail on how Red Hat provides support for bundled community dynamic plugins is available on the https://access.redhat.com/policy/developerhub-support-policy[Red Hat Developer Support Policy] page.
-====
-
-== For administrators
 
-To install and configure the Ansible plugins, see
-{ansible-automation-platform-docs-link}/html-single/installing_ansible_plug-ins_for_red_hat_developer_hub/index[_Installing Ansible plug-ins for {product}_].
-
-== For users
+====
 
-To use the Ansible plugins, see
-{ansible-automation-platform-docs-link}/html-single/using_ansible_plug-ins_for_red_hat_developer_hub/index[_Using Ansible plug-ins for {product}_].
+.Additional resources
+* link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Scope].
+* link:https://access.redhat.com/policy/developerhub-support-policy[Red Hat Developer Support Policy]
+* {ansible-automation-platform-docs-link}/html-single/installing_ansible_plug-ins_for_red_hat_developer_hub/index[Installing Ansible plug-ins for {product}]
+* {ansible-automation-platform-docs-link}/html-single/using_ansible_plug-ins_for_red_hat_developer_hub/index[Using Ansible plug-ins for {product}]
 
diff --git a/modules/dynamic-plugins/proc-example-third-party-plugin-installation.adoc b/modules/dynamic-plugins/proc-example-third-party-plugin-installation.adoc
@@ -1,10 +1,11 @@
-:_mod-docs-content-type: REFERENCE
+:_mod-docs-content-type: PROCEDURE
 
 [id="ref-example-third-party-plugin-installation_{context}"]
 = Example of installing a third-party plugin in {product}
 
-This section describes the process for integrating the link:https://github.com/backstage/community-plugins/tree/main/workspaces/todo/plugins[Todo plugin] into your {product-short}.
+This section describes the process for integrating the Todo plugin into your {product-short}.
 
+.Procedure
 . *Obtain the third-party plugin source code*: Clone the plugins repository and navigate to the link:https://github.com/backstage/community-plugins/tree/main/workspaces/todo/plugins[Todo plugin] directory:
 +
 --
diff --git a/modules/dynamic-plugins/ref-community-plugins.template.adoc b/modules/dynamic-plugins/ref-community-plugins.template.adoc
diff --git a/modules/dynamic-plugins/ref-keycloak-plugin-metrics.adoc b/modules/dynamic-plugins/ref-keycloak-plugin-metrics.adoc
diff --git a/modules/observe/con-audit-log-config.adoc b/modules/observe/con-audit-log-config.adoc
diff --git a/modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc b/modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc
