Update additional capabilities title structure (#2081) (#2095)

jmagak · GitHub Actions · claude · web-flow · commit 32b9348b6e00 · 2026-04-23T09:32:59.000-04:00
* Rename additional-rhdh-capabilities.adoc to ref-rhdh-capabilities.adoc and add REFERENCE content type metadata This change applies the same CQA compliance fixes from PR 2080: - Rename additional-rhdh-capabilities.adoc to ref-rhdh-capabilities.adoc - Add :_mod-docs-content-type: REFERENCE metadata - Update master.adoc to reference the renamed file * Apply CQA compliance fixes to ref-rhdh-capabilities.adoc Apply the same CQA fixes as in PR 2080: - Change block titles to plain text with colons (.Overview → Overview:) - Replace "Backstage" with {backstage} attribute throughout - Fix Example section formatting These changes ensure CQA compliance for DITA conversion. * Fix additional CQA violations in ref-rhdh-capabilities.adoc - Replace "Technology Preview" with {technology-preview} attribute - Replace "Developer Preview" with {developer-preview} attribute - Replace "The Backstage entity reference" with "The {backstage} entity reference" * Apply new updates * Update titles * Fix CQA violations in additional capabilities title - Rename directory to titles/additional_title-additional-rhdh-capabilities (CQA-00b compliance) - Add [role="_abstract"] marker to ref-rhdh-capabilities.adoc (CQA-09) - Add [id="{context}"] to master.adoc (CQA-02) - Auto-fix nested section levels and conditional code (CQA-01) * Remove self-referential language from abstract Replace "This document includes" with "Includes" to comply with CQA-08. * Apply CQA suggestion * Trigger preview rebuild Empty commit to re-trigger the PR preview build workflow. * Fix PR preview deployment to use correct event context Changed all instances of `github.event.number` to `github.event.pull_request.number` in the PR workflow. For pull_request_target events, `github.event.number` may be undefined, causing the build script to default to branch "main" instead of "pr-{number}", resulting in preview deployments going to the wrong directory. This fixes the issue where PR previews were being deployed to `main/` instead of `pr-{number}/`, making preview URLs return 404. * Revert "Fix PR preview deployment to use correct event context" This reverts commit 1863b4a. * Minor fix * Update sections --------- Co-authored-by: GitHub Actions <github-actions@github.com> Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
diff --git a/titles/additional_title-additional-rhdh-capabilities/additional-capabilities/ref-rhdh-capabilities.adoc b/titles/additional_title-additional-rhdh-capabilities/additional-capabilities/ref-rhdh-capabilities.adoc
@@ -1,14 +1,10 @@
+:_mod-docs-content-type: REFERENCE
 [id='additional-rhdh-capabilities_{context}']
 
-*DISCLAIMER:* This document includes early, evolving, or supplemental content related to {product-very-short} capabilities. It may cover newly introduced features, features that are still maturing, or supported functionality that is not yet fully documented in the official product documentation. This content is authored by {company-name} experts, but has not yet been tested on every supported configuration.
+[role="_abstract"]
+*DISCLAIMER:* This is an early, evolving, or supplemental content related to {product} capabilities. Content may cover newly introduced features, features that are still maturing, or supported functionality that is not yet fully documented in the official product documentation.
 
-The content in this document describes preview or early-stage capabilities that are provided to offer early guidance and improve discoverability while the documentation continues to evolve. As a result, the structure, depth, and level of detail might vary. Information may be updated, reorganized, or removed based on product changes and user feedback.
-
-Where applicable, individual features retain their respective support status (for example, Supported, Technology Preview, or Developer Preview). Refer to the feature-specific documentation for details about the link:https://access.redhat.com/support[support] scope.
-
-include::../artifacts/snip-technology-preview.adoc[]
-
-include::../artifacts/snip-developer-preview.adoc[]
+Content is authored by {company-name} experts, but has not yet been tested on every supported configuration. Preview or early-stage capabilities are provided to offer early guidance and improve discoverability while the documentation continues to evolve. As a result, the structure, depth, and level of detail might vary. Information may be updated, reorganized, or removed based on product changes and user feedback. Individual features retain their respective support status as documented. Refer to the feature-specific documentation for details about the link:https://access.redhat.com/support[support] scope.
 
 == Integrate Argo CD notifications with {product}
 
@@ -24,9 +20,10 @@ This guide explains how to configure Argo CD to send notifications directly to t
 _This task is intended for Platform Engineers; it involves cluster-wide runtime changes_.
 ====
 
-.Overview
+Overview:
 
 The following diagram illustrates the flow from an Argo CD event in the cluster to the {product-very-short} user interface.
+[subs="+attributes,+quotes"]
 ----
 ┌────────────────────────────────────────────────────────────────────┐
 │                    Kubernetes / OpenShift Cluster                  │
@@ -42,14 +39,14 @@ The following diagram illustrates the flow from an Argo CD event in the cluster
                                               │ (with auth token)
                                               ▼
                     ┌────────────────────────────────────────────┐
-                    │              Backstage                     │
+                    │              {backstage}                     │
                     │  Endpoint: /api/notifications/notifications│
                     │  ──────────────────────────────────────────│
                     │  Shows notifications to users in the UI    │
                     └────────────────────────────────────────────┘
 ----
 
-.Prerequisites
+Prerequisites:
 
 Before you begin, make sure you have the following:
 
@@ -59,7 +56,7 @@ Before you begin, make sure you have the following:
 
 ---
 
-.Part 1: Enable the notifications plugin in {product-very-short}
+Part 1: Enable the notifications plugin in {product-very-short}:
 
 *Environment*: {product-very-short} Configuration.
 
@@ -99,7 +96,7 @@ backend:
 
 ---
 
-.Part 2: Argo CD configuration
+Part 2: Argo CD configuration:
 
 *Environment*: OpenShift Cluster (executing `oc` commands).
 
@@ -414,7 +411,7 @@ kubectl apply -f argocd-notifications-cm.yaml
 
 ---
 
-.Part 3: Enable notifications for your application
+Part 3: Enable notifications for your application:
 
 *Environment*: OpenShift Cluster (Argo CD Application manifests).
 
@@ -424,23 +421,23 @@ Update individual Argo CD `Application` manifests to enable the notifications fo
 
 Each Argo CD Application that should send notifications needs two things:
 
-1. **The Backstage entity reference** - tells Argo CD which {backstage} entity should receive notifications.
+1. **The {backstage} entity reference** - tells Argo CD which {backstage} entity should receive notifications.
 2. **Trigger subscriptions** - tells Argo CD which events to notify about.
 
 [IMPORTANT]
 ====
 The subscription annotation format is `notifications.argoproj.io/subscribe.<trigger-name>.<service>`. The trigger name must match exactly what you configured (with the `-backstage` suffix).
 ====
 
-[source,yaml]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:
   name: my-application
   namespace: openshift-gitops
   annotations:
-    # 1. Map to Backstage entity (REQUIRED)
+    # 1. Map to {backstage} entity (REQUIRED)
     backstage.io/entity-ref: 'component:default/my-application'
 
     # 2. Subscribe to notification triggers (add the ones you want)
@@ -454,7 +451,7 @@ spec:
 
 ---
 
-.Example: Complete Setup Flow
+Example: Complete Setup Flow:
 **Scenario**
 
 You have a service called `order-service` managed by Argo CD, and you want the team to receive {backstage} notifications on sync events.
@@ -479,7 +476,7 @@ spec:
 
 . *Argo CD Application*
 +
-[source,yaml]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 # argocd/order-service-app.yaml
 apiVersion: argoproj.io/v1alpha1
@@ -488,7 +485,7 @@ metadata:
   name: order-service
   namespace: openshift-gitops
   annotations:
-    # Link to Backstage entity
+    # Link to {backstage} entity
     backstage.io/entity-ref: 'component:default/order-service'
     # Subscribe to notifications (note the -backstage suffix in trigger names)
     notifications.argoproj.io/subscribe.on-deployed-backstage.backstage: ''
@@ -513,14 +510,14 @@ spec:
 
 1. **Developer pushes code** → Argo CD detects change and syncs.
 2. **Sync succeeds** → Argo CD notifications controller fires `on-deployed-backstage` trigger.
-3. **Webhook sent** → POST to Backstage `/api/notifications/notifications`.
-4. **Notification appears** → Team sees "🚀 order-service - Deployed" in Backstage with a link to Argo CD.
+3. **Webhook sent** → POST to {backstage} `/api/notifications/notifications`.
+4. **Notification appears** → Team sees "🚀 order-service - Deployed" in {backstage} with a link to Argo CD.
 
 ---
 
 === Troubleshooting
 
-=== Notifications not appearing in {product-very-short}
+*Notifications not appearing in {product-very-short}*
 
 1. **Check notifications controller is running:**
 +
@@ -557,7 +554,7 @@ kubectl get configmap argocd-notifications-cm -n openshift-gitops -o jsonpath='{
 kubectl get application my-app -n openshift-gitops -o jsonpath='{.metadata.annotations}' | jq .
 ----
 
-=== "notification service 'backstage' is not supported"
+*"notification service 'backstage' is not supported"*
 
 This error means the webhook service is not configured.
 
@@ -568,7 +565,7 @@ Common causes include the following:
 
 **Solution:** Use the `NotificationsConfiguration` CR for OpenShift GitOps (see Part 2).
 
-=== Webhook Returns 400 Bad Request / "not valid JSON"
+*Webhook Returns 400 Bad Request / "not valid JSON"*
 
 This means the trigger is using the wrong template format (text instead of JSON).
 
@@ -583,7 +580,7 @@ Common causes include the following:
 * Trigger: `trigger.on-sync-succeeded-backstage`
 * Subscription: `notifications.argoproj.io/subscribe.on-sync-succeeded-backstage.backstage`
 
-=== Link Shows *<no value>* or Broken URL
+*Link Shows *<no value>* or Broken URL*
 
 The `{{.context.argocdUrl}}` template variable is not configured.
 
@@ -610,11 +607,11 @@ data:
     argocdUrl: https://your-argocd-url.com
 ----
 
-=== Authentication Errors
+*Authentication Errors*
 
 If you see `401 Unauthorized` or token errors:
 
-1. Verify the token in `argocd-notifications-secret` matches your Backstage config.
+1. Verify the token in `argocd-notifications-secret` matches your {backstage} config.
 2. Check the Authorization header format: `Bearer $backstage-token`.
 3. Restart the notifications controller after secret changes:
 +
@@ -628,14 +625,14 @@ kubectl rollout restart deployment -n openshift-gitops -l app.kubernetes.io/name
 === Security Considerations
 
 1. **Use strong tokens** - Generate random tokens with sufficient entropy.
-2. **Rotate tokens periodically** - Update both Argo CD secret and Backstage config.
-3. **Use HTTPS** - Ensure Backstage is accessible over HTTPS in production.
+2. **Rotate tokens periodically** - Update both Argo CD secret and {backstage} config.
+3. **Use HTTPS** - Ensure {backstage} is accessible over HTTPS in production.
 4. **Network policies** - Consider restricting which pods can reach {backstage}.
 
 ---
 
 === Additional Resources
 
 * link:https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/[Argo CD Notifications Documentation]
-* link:https://backstage.io/docs/notifications/[Backstage Notifications Plugin]
+* link:https://backstage.io/docs/notifications/[{backstage} Notifications Plugin]
 * link:https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/services/webhook/[Argo CD Webhook Service Configuration]
diff --git a/titles/additional_title-additional-rhdh-capabilities/master.adoc b/titles/additional_title-additional-rhdh-capabilities/master.adoc
@@ -8,11 +8,10 @@ include::artifacts/attributes.adoc[]
 :abstract: Explore emerging, evolving, and supplemental capabilities in {product}, including new features and supported functionality not yet fully covered in the core documentation.
 :imagesdir: images
 
+[id="{context}"]
 = {title}
 
 [role="_abstract"]
-{abstract}
+Explore emerging, evolving, and supplemental capabilities in {product}. This content covers new features, preview technologies, and supported functionality not yet fully documented in the core documentation.
 
-include::artifacts/snip-developer-preview.adoc[]
-
-include::additional-capabilities/additional-rhdh-capabilities.adoc[]
+include::additional-capabilities/ref-rhdh-capabilities.adoc[]
