From cfef236bda3f05d1dac1e06cd74bbbe3c24ac8bf Mon Sep 17 00:00:00 2001
From: linfraze <lfrazier@redhat.com>
Date: Fri, 13 Jun 2025 17:00:49 -0400
Subject: [PATCH 1/8] RHIDP-7202: Doc procs for generating TechDocs pipeline
 with GitHub Actions and embedding videos

---
 assemblies/assembly-configuring-techdocs.adoc | 16 +++--
 assemblies/assembly-using-techdocs.adoc       |  6 ++
 .../proc-techdocs-using-odf-storage.adoc      |  2 +-
 ...-techdocs-configure-amazon-s3-storage.adoc | 67 ++++++++++++++++++
 .../techdocs/proc-techdocs-embed-videos.adoc  | 70 +++++++++++++++++++
 ...proc-techdocs-pipeline-github-actions.adoc | 61 ++++++++++++++++
 6 files changed, 216 insertions(+), 6 deletions(-)
 create mode 100644 modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc
 create mode 100644 modules/techdocs/proc-techdocs-embed-videos.adoc
 create mode 100644 modules/techdocs/proc-techdocs-pipeline-github-actions.adoc

diff --git a/assemblies/assembly-configuring-techdocs.adoc b/assemblies/assembly-configuring-techdocs.adoc
index 8afb63a65e..889d045b1d 100644
--- a/assemblies/assembly-configuring-techdocs.adoc
+++ b/assemblies/assembly-configuring-techdocs.adoc
@@ -1,7 +1,7 @@
 :_mod-docs-content-type: ASSEMBLY
 :context: configuring-techdocs
 [id="{context}"]
-= TechDocs configuration
+= Configuring TechDocs
 
 The TechDocs plugin is preinstalled and enabled on a {product-short} instance by default. You can disable or enable the TechDocs plugin, and change other parameters, by configuring the {product} Helm chart or the {product} Operator ConfigMap.
 
@@ -19,18 +19,24 @@ After you configure {odf-name} to store the files that TechDocs generates, you c
 
 * For more information, see link:{configuring-dynamic-plugins-book-url}[{configuring-dynamic-plugins-book-title}].
 
+//configuring storage
 include::modules/customizing-techdocs/con-techdocs-configure-storage.adoc[leveloffset=+1]
 
+//configuring storage - ODF
 include::modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc[leveloffset=+2]
 
-include::modules/customizing-techdocs/proc-techdocs-configure-odf-helm.adoc[leveloffset=+2]
+include::modules/customizing-techdocs/proc-techdocs-configure-odf-helm.adoc[leveloffset=+3]
 
-include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-helm.adoc[leveloffset=+3]
+include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-helm.adoc[leveloffset=+4]
 
-include::modules/customizing-techdocs/proc-techdocs-configure-odf-operator.adoc[leveloffset=+2]
+include::modules/customizing-techdocs/proc-techdocs-configure-odf-operator.adoc[leveloffset=+3]
 
-include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-operator.adoc[leveloffset=+3]
+include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-operator.adoc[leveloffset=+4]
 
+//configuring storage - Amazon S3
+include::modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc[leveloffset=+2]
+
+//configuring CI/CD
 include::modules/customizing-techdocs/con-techdocs-config-cicd.adoc[leveloffset=+1]
 
 include::modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc[leveloffset=+2]
diff --git a/assemblies/assembly-using-techdocs.adoc b/assemblies/assembly-using-techdocs.adoc
index 61990c879a..1156f21eaf 100644
--- a/assemblies/assembly-using-techdocs.adoc
+++ b/assemblies/assembly-using-techdocs.adoc
@@ -12,3 +12,9 @@ include::modules/techdocs/proc-techdocs-find-docs.adoc[leveloffset=+1]
 include::modules/techdocs/proc-techdocs-view-docs.adoc[leveloffset=+1]
 
 include::modules/techdocs/proc-techdocs-edit-docs.adoc[leveloffset=+1]
+
+//embedding videos
+include::modules/techdocs/proc-techdocs-embed-videos.adoc[leveloffset=+1]
+
+//generating pipelines with GitHub Actions
+include::modules/techdocs/proc-techdocs-pipeline-github-actions.adoc[leveloffset=+1]
diff --git a/modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc b/modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc
index b76e7fe04f..c1f2053a25 100644
--- a/modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc
+++ b/modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 [id="proc-techdocs-using-odf-storage_{context}"]
-= Using {odf-name} for file storage
+= Configuring {odf-name} for file storage
 
 You can configure {odf-name} to store the files that TechDocs generates instead of relying on other cloud storage solutions.
 
diff --git a/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc b/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc
new file mode 100644
index 0000000000..f21c93a943
--- /dev/null
+++ b/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc
@@ -0,0 +1,67 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-using-techdocs.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-techdocs-configure-amazon-s3-storage_{context}"]
+= Configuring Amazon S3 for file storage
+
+ You can create a dedicated Amazon S3 bucket to store TechDocs sites. {product} uploads TechDocs to this bucket and serves them from the same location.
+
+.Prerequisites
+
+* You are logged in to your AWS account.
+
+.Procedure
+. On the AWS console, create an AWS S3 bucket.
+.. On the *Create bucket* page, enter a *Bucket name* and use the default selections for all other settings.
+.. Create an IAM policy to give authorized users permissions to generate and publish TechDocs for your organization.
+.. On the *Create policy > Specify permissions* page, enter the following JSON content into the *Policy editor*:
++
+[source,JSON,subs="+quotes,+attributes"]
+----
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "TechDocsList",
+            "Effect": "Allow",
+            "Action": "s3:ListBucket",
+            "Resource": "arn:aws:s3:::_<bucket_name>_"
+        },
+        {
+            "Sid": "TechDocsObjects",
+            "Effect": "Allow",
+            "Action": [
+                "s3:GetObject",
+                "s3:PutObject",
+                "s3:DeleteObject",
+                "s3:DeleteObjectVersion"
+            ],
+            "Resource": "arn:aws:s3:::_<bucket_name>_/*"
+        }
+    ]
+}
+----
++
+where
+
+_<bucket_name>_ :: Specifies the name of your Amazon S3 bucket.
++
+.. On the *Create policy > Specify permissions* page, enter a *Policy name*.
+. Create a user and assign the IAM policy.
+.. On the *Create user > Specify user details* page, enter a *User name*.
+.. On the *Create user > Set permissions* page, select *Attach policies directly* and select the permissions policy that you created.
+. Generate a new access key and a new secret access key.
++
+[NOTE]
+====
+You can use the newly created access keys to generate a TechDocs pipeline with GitHub Actions.
+====
+
+.Verification
+. Go to your Amazon S3 bucket to see a set of static site files in your *Objects* list.
+////
+.Next steps
+* xref:proc-techdocs-pipeline-github-actions_{context}[Generating a TechDocs pipeline with GitHub Actions]
+////
diff --git a/modules/techdocs/proc-techdocs-embed-videos.adoc b/modules/techdocs/proc-techdocs-embed-videos.adoc
new file mode 100644
index 0000000000..d9953e42da
--- /dev/null
+++ b/modules/techdocs/proc-techdocs-embed-videos.adoc
@@ -0,0 +1,70 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-using-techdocs.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-techdocs-embed-video_{context}"]
+= Embedding videos into TechDocs
+
+You can use `<iframe>` elements to embed videos into your TechDocs.
+
+.Procedure
+
+. In the section of the TechDocs file that you want to embed a video into, add the following configuration:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+<iframe
+  width="_<video_width>_"
+  height="_<video_height>_"
+  src="_<video_url>_"
+  title="_<video_title>_"
+  frameborder="_<frame_border>_"
+  allow="picture-in-picture"
+  allowfullscreen>
+</iframe>
+----
++
+where
+
+_<video_width>_ :: Specifies the width of the video in number of pixels, for example, `672`.
+_<video_height>_ :: Specifies the height of the video in number of pixels, for example, `378`.
+_<video_url>_ :: Specifies the url of the video, for example, `https://www.youtube.com/watch?v=LB1w8hjBt5k`.
+_<video_title>_ :: Specifies the title of the video, for example, `{product} Overview Video`.
+_<frame_border>_ :: Specifies the size of the frame border in number of pixels, for example, `0`. Use a value of `0` for no border.
++
+[NOTE]
+====
+TechDocs uses DOMPurify to sanitize HTML. To prevent DOMPurify from removing the `<iframe>` elements, you must list every permitted video host, such as www.youtube.com, under the `techdocs.sanitizer.allowedIframeHosts` section of your `app-config.yaml` file. You must also add the video host to the `backend.csp` section of your `app-config.yaml` file.
+====
+. In the `frame-src` and `allowedIframeHosts` fields of your `app-config.yaml` file, add any video hosts that you want to use. For example:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+backend:
+        csp:
+connect-src: ['https:']
+frame-src: ['https://www.youtube.com/']
+techdocs:
+  builder: external
+  sanitizer:
+    allowedIframeHosts:
+      - www.youtube.com
+  publisher:
+    type: awsS3
+    awsS3:
+      bucketName: ${AWS_S3_BUCKET_NAME}
+      accountId: ${AWS_ACCOUNT_ID}
+      region: ${AWS_REGION}
+----
++
+. To authenticate with AWS, add the following configuration to your `app-config.yaml` file. For example:
++
+[source,yaml]
+----
+aws:
+  accounts:
+    - accountId: ${AWS_ACCOUNT_ID}
+      accessKeyId: ${AWS_ACCESS_KEY_ID}
+      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
+----
diff --git a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
new file mode 100644
index 0000000000..d47e5f1737
--- /dev/null
+++ b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-using-techdocs.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-techdocs-pipeline-github-actions_{context}"]
+= Generating TechDocs Pipelines with GitHub Actions
+
+{product} ({product-very-short}) includes a built-in TechDocs builder, however, the default setup is not intended for production use. Deploying TechDocs documentation in a production environment involves the following actions:
+
+* *Building the documentation in a CI/CD system*
+* *Publishing the generated documentation site to external object storage*, such as AWS S3, to ensure that the generated documentation persists between restarts of {product-very-short} and can handle larger documentation workloads.
+* *Configuring TechDocs in your {product-very-short} deployment to run in read-only mode* so that TechDocs reads the static generated documentation files from the cloud storage bucket without attempting to generate them at runtime.
+
+You can implement a TechDocs pipeline using GitHub Actions to automatically generate and publish your TechDocs whenever a user in your organization makes a change to a documentation file stored in your GitHub respository.
+
+.Prerequisites
+
+* The TechDocs plugin is enabled and configured on your {product-very-short} instance.
+* Your organization has documentation files stored in a remote repository.
+* You have an mkdocs.yaml file located in the root directory of your repository.
+* You have the `catalog.entity.create` and `catalog.location.create` permissions to import documentation into TechDocs from a remote repository.
+* You have an AWS S3 bucket created to store your TechDocs sites.
+* Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.
+* An IAM User has been created, the necessary policy attached, and an access key generated.
+
+.Procedure
+
+. Set up the GitHub Actions workflow
+.. On GitHub, create a fork of the `rhdh-techdocs-pipeline` repository.
++
+[NOTE]
+====
+The `rhdh-techdocs-pipeline` repository contains a `generate-and-publish-techdocs.yaml` workflow that automatically generates TechDocs from the docs folder and publishes them to an Amazon S3 bucket.
+====
++
+.. Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled.
+.. Add the *Repository secrets* required to connect the workflow to your AWS account.
++
+[NOTE]
+====
+The default `mkdocs.yaml` file in the `rhdh-techdocs-pipeline` workflow installs the `techdocs-core` and `minify` plugins.
+====
+.. Optional: Modify the default structure of the `rhdh-techdocs-pipeline` repository or the default files within it to meet the needs of your organization.
+.. Optional: Add other `mkdocs` plugins that you want to use by adding the name of the plugins to the `plugins` section of the `mkdocs.yaml` file and to the `steps.name: install mkdocs and mkdocs plugins` section of the `generate-and-publish-techdocs.yaml` file.
+. Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance.
+.. In the Developer perspective of {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
+.. In the `techdocs` section of the `app-config.yaml` file, set `builder` to `external`.
+.. Set `publisher.type` to `awsS3`.
+.. In the `aws` section, set `accounts.accountId` to `$(AWS_ACCOUNT_ID)`, set `accounts.accessKeyId` to `$(AWS_ACCESS_KEY_ID)`, and set `accounts.secretAccessKey` to `$(AWS_SECRET_ACCESS_KEY)`.
+.. In the `catalog` section, set `locations.type` to `url` and set `locations.target` to the url to the `catalog-info.yaml` file in your `rhdh-techdocs-pipeline` repository.
+. Click *Save*.
+. In the navigation menu of the {ocp-short} console, click *Topology* and restart the pod.
++
+[NOTE]
+====
+Changes to the `docs` folder or the `mkdocs.yaml` file trigger the `rhdh-techdocs-pipeline` workflow to run. After the `rhdh-techdocs-pipeline` workflow runs successfully, the generated TechDocs are uploaded to your Amazon S3 bucket.
+====
+
+.Verification
+. Go to your {product-very-short} instance and click *Docs* to see the TechDocs served from your Amazon S3 bucket.

From ac5bd69b5dfb83862a3da68de38841b3e5b7d551 Mon Sep 17 00:00:00 2001
From: linfraze <lfrazier@redhat.com>
Date: Tue, 24 Jun 2025 13:35:35 -0400
Subject: [PATCH 2/8] RHIDP-7202: Apply SME comments

---
 assemblies/assembly-configuring-techdocs.adoc | 11 ++----
 .../con-techdocs-config-cicd.adoc             |  2 +
 .../con-techdocs-configure-storage.adoc       |  2 +-
 .../proc-techdocs-config-cicd-prep-repo.adoc  |  2 +
 .../proc-techdocs-generate-site.adoc          |  2 +
 .../proc-techdocs-publish-site.adoc           |  2 +
 ...-techdocs-configure-amazon-s3-storage.adoc | 12 ++++--
 .../techdocs/proc-techdocs-embed-videos.adoc  | 19 ++++-----
 ...proc-techdocs-pipeline-github-actions.adoc | 39 ++++++++++++++-----
 9 files changed, 56 insertions(+), 35 deletions(-)

diff --git a/assemblies/assembly-configuring-techdocs.adoc b/assemblies/assembly-configuring-techdocs.adoc
index 889d045b1d..dc67415448 100644
--- a/assemblies/assembly-configuring-techdocs.adoc
+++ b/assemblies/assembly-configuring-techdocs.adoc
@@ -22,6 +22,9 @@ After you configure {odf-name} to store the files that TechDocs generates, you c
 //configuring storage
 include::modules/customizing-techdocs/con-techdocs-configure-storage.adoc[leveloffset=+1]
 
+//configuring storage - Amazon S3
+include::modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc[leveloffset=+2]
+
 //configuring storage - ODF
 include::modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc[leveloffset=+2]
 
@@ -33,14 +36,6 @@ include::modules/customizing-techdocs/proc-techdocs-configure-odf-operator.adoc[
 
 include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-operator.adoc[leveloffset=+4]
 
-//configuring storage - Amazon S3
-include::modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc[leveloffset=+2]
-
 //configuring CI/CD
 include::modules/customizing-techdocs/con-techdocs-config-cicd.adoc[leveloffset=+1]
 
-include::modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc[leveloffset=+2]
-
-include::modules/customizing-techdocs/proc-techdocs-generate-site.adoc[leveloffset=+2]
-
-include::modules/customizing-techdocs/proc-techdocs-publish-site.adoc[leveloffset=+2]
diff --git a/modules/customizing-techdocs/con-techdocs-config-cicd.adoc b/modules/customizing-techdocs/con-techdocs-config-cicd.adoc
index 604542179a..d73de99d55 100644
--- a/modules/customizing-techdocs/con-techdocs-config-cicd.adoc
+++ b/modules/customizing-techdocs/con-techdocs-config-cicd.adoc
@@ -1,3 +1,5 @@
+// ARCHIVED
+
 :_mod-docs-content-type: CONCEPT
 [id="con-techdocs-config-cicd_{context}"]
 = Configuring CI/CD to generate and publish TechDocs sites
diff --git a/modules/customizing-techdocs/con-techdocs-configure-storage.adoc b/modules/customizing-techdocs/con-techdocs-configure-storage.adoc
index f193aa8145..8e4cc54c3c 100644
--- a/modules/customizing-techdocs/con-techdocs-configure-storage.adoc
+++ b/modules/customizing-techdocs/con-techdocs-configure-storage.adoc
@@ -2,4 +2,4 @@
 [id="con-techdocs-configure-storage_{context}"]
 = Configuring storage for TechDocs files
 
-The TechDocs publisher stores generated files in local storage or in cloud storage, such as {odf-name}, Google GCS, AWS S3, or Azure Blob Storage.
+The TechDocs publisher stores generated files in local storage or in cloud storage, such as AWS S3 or {odf-name}.
diff --git a/modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc b/modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc
index 4a4bc7a951..7bc132a3a0 100644
--- a/modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc
+++ b/modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc
@@ -1,3 +1,5 @@
+// ARCHIVED
+
 :_mod-docs-content-type: PROCEDURE
 [id="proc-techdocs-config-cicd-prep-repo_{context}"]
 = Preparing your repository for CI
diff --git a/modules/customizing-techdocs/proc-techdocs-generate-site.adoc b/modules/customizing-techdocs/proc-techdocs-generate-site.adoc
index d70d0e61c7..85d50640a7 100644
--- a/modules/customizing-techdocs/proc-techdocs-generate-site.adoc
+++ b/modules/customizing-techdocs/proc-techdocs-generate-site.adoc
@@ -1,3 +1,5 @@
+// ARCHIVED
+
 :_mod-docs-content-type: PROCEDURE
 [id="proc-techdocs-generate-site_{context}"]
 = Generating the TechDocs site
diff --git a/modules/customizing-techdocs/proc-techdocs-publish-site.adoc b/modules/customizing-techdocs/proc-techdocs-publish-site.adoc
index fc8e22f581..4802e911ba 100644
--- a/modules/customizing-techdocs/proc-techdocs-publish-site.adoc
+++ b/modules/customizing-techdocs/proc-techdocs-publish-site.adoc
@@ -1,3 +1,5 @@
+// ARCHIVED
+
 :_mod-docs-content-type: PROCEDURE
 [id="proc-techdocs-publish-site_{context}"]
 = Publishing the TechDocs site
diff --git a/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc b/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc
index f21c93a943..4e8d864ab7 100644
--- a/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc
+++ b/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc
@@ -10,7 +10,7 @@
 
 .Prerequisites
 
-* You are logged in to your AWS account.
+* You are logged in to your AWS account as an administrator.
 
 .Procedure
 . On the AWS console, create an AWS S3 bucket.
@@ -49,15 +49,19 @@ where
 _<bucket_name>_ :: Specifies the name of your Amazon S3 bucket.
 +
 .. On the *Create policy > Specify permissions* page, enter a *Policy name*.
-. Create a user and assign the IAM policy.
-.. On the *Create user > Specify user details* page, enter a *User name*.
-.. On the *Create user > Set permissions* page, select *Attach policies directly* and select the permissions policy that you created.
+. Assign the IAM policy to a new or existing user.
 . Generate a new access key and a new secret access key.
 +
 [NOTE]
 ====
 You can use the newly created access keys to generate a TechDocs pipeline with GitHub Actions.
 ====
+. From the {ocp-short} web console, click *Topology* > *Actions* > *Restart rollout* to restart the pod.
++
+[NOTE]
+====
+You must restart the pod to apply the configuration changes.
+====
 
 .Verification
 . Go to your Amazon S3 bucket to see a set of static site files in your *Objects* list.
diff --git a/modules/techdocs/proc-techdocs-embed-videos.adoc b/modules/techdocs/proc-techdocs-embed-videos.adoc
index d9953e42da..0dee42581e 100644
--- a/modules/techdocs/proc-techdocs-embed-videos.adoc
+++ b/modules/techdocs/proc-techdocs-embed-videos.adoc
@@ -8,6 +8,11 @@
 
 You can use `<iframe>` elements to embed videos into your TechDocs.
 
+.Prerequisites
+
+* An administrator has configured your AWS S3 bucket to store TechDocs sites.
+* An administrator has configured the appropriate `techdocs.sanitizer.allowedIframeHosts` and `backend.csp` settings in your `app-config.yaml` file.
+
 .Procedure
 
 . In the section of the TechDocs file that you want to embed a video into, add the following configuration:
@@ -37,7 +42,7 @@ _<frame_border>_ :: Specifies the size of the frame border in number of pixels,
 ====
 TechDocs uses DOMPurify to sanitize HTML. To prevent DOMPurify from removing the `<iframe>` elements, you must list every permitted video host, such as www.youtube.com, under the `techdocs.sanitizer.allowedIframeHosts` section of your `app-config.yaml` file. You must also add the video host to the `backend.csp` section of your `app-config.yaml` file.
 ====
-. In the `frame-src` and `allowedIframeHosts` fields of your `app-config.yaml` file, add any video hosts that you want to use. For example:
+. In the `frame-src` and `allowedIframeHosts` fields of your `app-config.yaml` file, add any video hosts that you want to use. You can add multiple. hosts. For example:
 +
 [source,yaml,subs="+quotes,+attributes"]
 ----
@@ -50,6 +55,7 @@ techdocs:
   sanitizer:
     allowedIframeHosts:
       - www.youtube.com
+      - _<additional_video_host_url>_
   publisher:
     type: awsS3
     awsS3:
@@ -57,14 +63,3 @@ techdocs:
       accountId: ${AWS_ACCOUNT_ID}
       region: ${AWS_REGION}
 ----
-+
-. To authenticate with AWS, add the following configuration to your `app-config.yaml` file. For example:
-+
-[source,yaml]
-----
-aws:
-  accounts:
-    - accountId: ${AWS_ACCOUNT_ID}
-      accessKeyId: ${AWS_ACCESS_KEY_ID}
-      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
-----
diff --git a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
index d47e5f1737..bd68495547 100644
--- a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
+++ b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
@@ -20,14 +20,14 @@ You can implement a TechDocs pipeline using GitHub Actions to automatically gene
 * Your organization has documentation files stored in a remote repository.
 * You have an mkdocs.yaml file located in the root directory of your repository.
 * You have the `catalog.entity.create` and `catalog.location.create` permissions to import documentation into TechDocs from a remote repository.
-* You have an AWS S3 bucket created to store your TechDocs sites.
+* You have an AWS S3 bucket to store your TechDocs sites.
 * Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.
-* An IAM User has been created, the necessary policy attached, and an access key generated.
+* An administrator has created an IAM User, attached the necessary policy, and generated an access key in the AWS console.
 
 .Procedure
 
 . Set up the GitHub Actions workflow
-.. On GitHub, create a fork of the `rhdh-techdocs-pipeline` repository.
+.. On GitHub, create a fork of the link:https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[`red-hat-developer-hub-customization-provider`] repository.
 +
 [NOTE]
 ====
@@ -35,7 +35,7 @@ The `rhdh-techdocs-pipeline` repository contains a `generate-and-publish-techdoc
 ====
 +
 .. Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled.
-.. Add the *Repository secrets* required to connect the workflow to your AWS account.
+.. Add the *Repository secrets* required to connect the workflow to your AWS account, for example, `TECHDOCS_S3_BUCKET_NAME`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`.
 +
 [NOTE]
 ====
@@ -43,12 +43,31 @@ The default `mkdocs.yaml` file in the `rhdh-techdocs-pipeline` workflow installs
 ====
 .. Optional: Modify the default structure of the `rhdh-techdocs-pipeline` repository or the default files within it to meet the needs of your organization.
 .. Optional: Add other `mkdocs` plugins that you want to use by adding the name of the plugins to the `plugins` section of the `mkdocs.yaml` file and to the `steps.name: install mkdocs and mkdocs plugins` section of the `generate-and-publish-techdocs.yaml` file.
-. Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance.
-.. In the Developer perspective of {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
-.. In the `techdocs` section of the `app-config.yaml` file, set `builder` to `external`.
-.. Set `publisher.type` to `awsS3`.
-.. In the `aws` section, set `accounts.accountId` to `$(AWS_ACCOUNT_ID)`, set `accounts.accessKeyId` to `$(AWS_ACCESS_KEY_ID)`, and set `accounts.secretAccessKey` to `$(AWS_SECRET_ACCESS_KEY)`.
-.. In the `catalog` section, set `locations.type` to `url` and set `locations.target` to the url to the `catalog-info.yaml` file in your `rhdh-techdocs-pipeline` repository.
+. In the Developer perspective of {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
+. Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance. For example:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+techdocs:
+  builder: external
+  publisher:
+    type: awsS3
+    awsS3:
+      bucketName: ${AWS_S3_BUCKET_NAME}
+      accountId: ${AWS_ACCOUNT_ID}
+      region: ${AWS_REGION}
+
+aws:
+  accounts:
+    - accountId: ${AWS_ACCOUNT_ID}
+      accessKeyId: ${AWS_ACCESS_KEY_ID}
+      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
+
+catalog:
+     locations:
+        - type: url
+          target: https://github.com/_<your_org>_/rhdh-techdocs-pipeline/blob/main/catalog-info.yaml
+----
 . Click *Save*.
 . In the navigation menu of the {ocp-short} console, click *Topology* and restart the pod.
 +

From 63dcd570d149e62575810f9e0474807fde28239c Mon Sep 17 00:00:00 2001
From: Heena Manwani <59050394+hmanwani-rh@users.noreply.github.com>
Date: Mon, 4 Aug 2025 17:28:03 +0530
Subject: [PATCH 3/8] Update
 modules/techdocs/proc-techdocs-pipeline-github-actions.adoc

Co-authored-by: Priyanka Abel <pabel@redhat.com>
---
 modules/techdocs/proc-techdocs-pipeline-github-actions.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
index bd68495547..5bf580b5ae 100644
--- a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
+++ b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
@@ -12,7 +12,7 @@
 * *Publishing the generated documentation site to external object storage*, such as AWS S3, to ensure that the generated documentation persists between restarts of {product-very-short} and can handle larger documentation workloads.
 * *Configuring TechDocs in your {product-very-short} deployment to run in read-only mode* so that TechDocs reads the static generated documentation files from the cloud storage bucket without attempting to generate them at runtime.
 
-You can implement a TechDocs pipeline using GitHub Actions to automatically generate and publish your TechDocs whenever a user in your organization makes a change to a documentation file stored in your GitHub respository.
+You can implement a TechDocs pipeline using GitHub Actions to automatically generate and publish your TechDocs whenever a user in your organization makes a change to a documentation file stored in your GitHub repository.
 
 .Prerequisites
 

From 41c905c8f70726f06628e7e0e4cdb09b47034487 Mon Sep 17 00:00:00 2001
From: Heena Manwani <59050394+hmanwani-rh@users.noreply.github.com>
Date: Mon, 4 Aug 2025 17:28:22 +0530
Subject: [PATCH 4/8] Update
 modules/techdocs/proc-techdocs-pipeline-github-actions.adoc

Co-authored-by: Priyanka Abel <pabel@redhat.com>
---
 modules/techdocs/proc-techdocs-pipeline-github-actions.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
index 5bf580b5ae..ad517977e7 100644
--- a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
+++ b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
@@ -26,7 +26,7 @@ You can implement a TechDocs pipeline using GitHub Actions to automatically gene
 
 .Procedure
 
-. Set up the GitHub Actions workflow
+. Set up the GitHub Actions workflow.
 .. On GitHub, create a fork of the link:https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[`red-hat-developer-hub-customization-provider`] repository.
 +
 [NOTE]

From d43f446dfd94b11ef31006d394e511b3f7b4fb90 Mon Sep 17 00:00:00 2001
From: Heena Manwani <59050394+hmanwani-rh@users.noreply.github.com>
Date: Mon, 4 Aug 2025 17:28:53 +0530
Subject: [PATCH 5/8] Update
 modules/techdocs/proc-techdocs-pipeline-github-actions.adoc

Co-authored-by: Priyanka Abel <pabel@redhat.com>
---
 modules/techdocs/proc-techdocs-pipeline-github-actions.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
index ad517977e7..27075e398c 100644
--- a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
+++ b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
@@ -41,7 +41,7 @@ The `rhdh-techdocs-pipeline` repository contains a `generate-and-publish-techdoc
 ====
 The default `mkdocs.yaml` file in the `rhdh-techdocs-pipeline` workflow installs the `techdocs-core` and `minify` plugins.
 ====
-.. Optional: Modify the default structure of the `rhdh-techdocs-pipeline` repository or the default files within it to meet the needs of your organization.
+.. Optional: Customize the default structure or files of the `rhdh-techdocs-pipeline` repository to meet the needs of your organization.
 .. Optional: Add other `mkdocs` plugins that you want to use by adding the name of the plugins to the `plugins` section of the `mkdocs.yaml` file and to the `steps.name: install mkdocs and mkdocs plugins` section of the `generate-and-publish-techdocs.yaml` file.
 . In the Developer perspective of {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
 . Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance. For example:

From de866236a7db5795dd527b0dd4de4cb7446813ec Mon Sep 17 00:00:00 2001
From: Heena Manwani <59050394+hmanwani-rh@users.noreply.github.com>
Date: Mon, 4 Aug 2025 17:29:29 +0530
Subject: [PATCH 6/8] Update
 modules/techdocs/proc-techdocs-pipeline-github-actions.adoc

Co-authored-by: Priyanka Abel <pabel@redhat.com>
---
 modules/techdocs/proc-techdocs-pipeline-github-actions.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
index 27075e398c..45c0ec841e 100644
--- a/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
+++ b/modules/techdocs/proc-techdocs-pipeline-github-actions.adoc
@@ -43,7 +43,7 @@ The default `mkdocs.yaml` file in the `rhdh-techdocs-pipeline` workflow installs
 ====
 .. Optional: Customize the default structure or files of the `rhdh-techdocs-pipeline` repository to meet the needs of your organization.
 .. Optional: Add other `mkdocs` plugins that you want to use by adding the name of the plugins to the `plugins` section of the `mkdocs.yaml` file and to the `steps.name: install mkdocs and mkdocs plugins` section of the `generate-and-publish-techdocs.yaml` file.
-. In the Developer perspective of {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
+. . In the navigation menu of the {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
 . Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance. For example:
 +
 [source,yaml,subs="+quotes,+attributes"]

From f67000dfb7bb2c7d28e400a50ef6aaad026067b6 Mon Sep 17 00:00:00 2001
From: Heena Manwani <59050394+hmanwani-rh@users.noreply.github.com>
Date: Mon, 4 Aug 2025 17:35:16 +0530
Subject: [PATCH 7/8] Update
 modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc

Co-authored-by: Priyanka Abel <pabel@redhat.com>
---
 modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc b/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc
index 4e8d864ab7..9e6dd2b875 100644
--- a/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc
+++ b/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc
@@ -16,7 +16,7 @@
 . On the AWS console, create an AWS S3 bucket.
 .. On the *Create bucket* page, enter a *Bucket name* and use the default selections for all other settings.
 .. Create an IAM policy to give authorized users permissions to generate and publish TechDocs for your organization.
-.. On the *Create policy > Specify permissions* page, enter the following JSON content into the *Policy editor*:
+.. On the *Create policy > Specify permissions* page, in the *Policy editor*, enter the following JSON content:
 +
 [source,JSON,subs="+quotes,+attributes"]
 ----

From a4629d9705df9c271d01013a467a28de305a4484 Mon Sep 17 00:00:00 2001
From: Heena Manwani <59050394+hmanwani-rh@users.noreply.github.com>
Date: Mon, 4 Aug 2025 17:35:45 +0530
Subject: [PATCH 8/8] Update modules/techdocs/proc-techdocs-embed-videos.adoc

Co-authored-by: Priyanka Abel <pabel@redhat.com>
---
 modules/techdocs/proc-techdocs-embed-videos.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/techdocs/proc-techdocs-embed-videos.adoc b/modules/techdocs/proc-techdocs-embed-videos.adoc
index 0dee42581e..d90317c7d3 100644
--- a/modules/techdocs/proc-techdocs-embed-videos.adoc
+++ b/modules/techdocs/proc-techdocs-embed-videos.adoc
@@ -42,7 +42,7 @@ _<frame_border>_ :: Specifies the size of the frame border in number of pixels,
 ====
 TechDocs uses DOMPurify to sanitize HTML. To prevent DOMPurify from removing the `<iframe>` elements, you must list every permitted video host, such as www.youtube.com, under the `techdocs.sanitizer.allowedIframeHosts` section of your `app-config.yaml` file. You must also add the video host to the `backend.csp` section of your `app-config.yaml` file.
 ====
-. In the `frame-src` and `allowedIframeHosts` fields of your `app-config.yaml` file, add any video hosts that you want to use. You can add multiple. hosts. For example:
+. In the `frame-src` and `allowedIframeHosts` fields of your `app-config.yaml` file, add any video hosts that you want to use. You can add multiple hosts. For example:
 +
 [source,yaml,subs="+quotes,+attributes"]
 ----