Chapter 3. Using TechDocs

Procedure

1. In the Red Hat Developer Hub navigation menu, click Docs.
2. On the Documentation page, use the search bar, filters, or both to locate the document that you want to view.

Procedure

1. In the Red Hat Developer Hub navigation menu, click Docs.
2. In the Documentation table, click the name of the document that you want to view.

3. On the book page, you can do any of the following optional actions:

   • Use installed add-ons that extend the functionality of the default TechDocs plugin.
   • Use the search bar to find keywords within the document.

   • Use any of the following methods to navigate the documentation in the book:

     • Use the Table of contents to navigate the any section of the document.
     • Use the navigation menu to navigate to any document in the book.
     • Click Next to navigate to the next sequential document in the book.

Procedure

1. In the Red Hat Developer Hub navigation menu, click Docs.
2. In the Documentation table, click the name of the document that you want to edit.
3. In the document, click the Edit this page icon to open the document in your remote repository.
4. In your remote repository, edit the document as needed.
5. Use the repository provider UI and your usual team processes to commit and merge your changes.

Procedure

1. In the section of the TechDocs file that you want to embed a video into, add the following configuration:

   <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, Red Hat Developer Hub 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.

2. 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:

   backend:
           csp:
   connect-src: ['https:']
   frame-src: ['https://www.youtube.com/']
   techdocs:
     builder: external
     sanitizer:
       allowedIframeHosts:
         - www.youtube.com
         - <additional_video_host_url>
     publisher:
       type: awsS3
       awsS3:
         bucketName: ${AWS_S3_BUCKET_NAME}
         accountId: ${AWS_ACCOUNT_ID}
         region: ${AWS_REGION}

Procedure

1. Set up the GitHub Actions workflow.

   1. 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.

   2. Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled.

   3. 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

      The default mkdocs.yaml file in the rhdh-techdocs-pipeline workflow installs the techdocs-core and minify plugins.

   4. Optional: Customize the default structure or files of the rhdh-techdocs-pipeline repository to meet the needs of your organization.
   5. 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.
2. . In the navigation menu of the OpenShift Container Platform console, click ConfigMaps and select your RHDH app-config.yaml file.

3. Update the app-config.yaml file to enable your Amazon S3 bucket to serve TechDocs to your RHDH instance. For example:

   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

4. Click Save.

5. In the navigation menu of the OpenShift Container Platform 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

1. Go to your RHDH instance and click Docs to see the TechDocs served from your Amazon S3 bucket.