Red Hat Developer Hub 1.10

Manage and consume technical documentation within Red Hat Developer Hub

Managing the documentation lifecycle - add, search, view, and edit content - using the TechDocs plugin in Red Hat Developer Hub (RHDH)

Red Hat Customer Content Services

Abstract

The TechDocs plugin provides complete documentation lifecycle management. Authorized administrators set up the service, allowing developers to manage documentation directly in Red Hat Developer Hub (RHDH), including adding, searching, viewing, and editing content.

1. Add documentation to TechDocs for your project
2. Search for relevant content
3. Access and navigate documentation
4. Make changes to project documentation in TechDocs
5. Add video content to enhance TechDocs
6. Streamline documentation builds using GitHub Actions

1. Add documentation to TechDocs for your project

After an administrator configures TechDocs, a developer can add documentation by importing from a remote repository, creating standalone docs, or enabling docs for an existing catalog entity.

1.1. Import documentation into TechDocs from a remote repository

Teams can store their documentation files in the same remote repository where they store their code files. You can import documentation into your TechDocs plugin from a remote repository that contains the documentation files that your team uses.

Prerequisites

Your organization has documentation files stored in a remote repository.
You have a mkdocs.yaml file 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.

Procedure

In your Red Hat Developer Hub instance, click Catalog > Self-service > Register Existing Component.
In the Select URL box, enter the URL to the catalog-info.yaml file that you want to import from your repository using the following format:
https://github.com/<project_name>/<repo_name>/blob/<branch_name>/<file_directory>/catalog-info.yaml
Click Analyze
Click Finish

Verification

In the Developer Hub navigation menu, click Docs.
Verify that the documentation that you imported is listed in the table on the Documentation page.

1.2. Create standalone documentation in TechDocs

You can create standalone documentation in TechDocs for content that is not tied to a specific codebase, such as onboarding guides, architecture overviews, or team runbooks.

Prerequisites

An administrator has configured the TechDocs plugin.
You have the catalog.entity.create and catalog.location.create permissions.

Procedure

Create a directory for your documentation project with the following structure:
```
my-documentation/
  catalog-info.yaml
  mkdocs.yml
  docs/
    index.md
```

Create a catalog-info.yaml file that defines a documentation entity:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-documentation
  description: Onboarding guide for new team members
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: documentation
  lifecycle: production
  owner: group:default/my-team

Create an mkdocs.yml file to configure the documentation site:

site_name: My Documentation
nav:
  - Home: index.md
plugins:
  - techdocs-core

Create a docs/ directory containing at least an index.md file with your documentation content in Markdown.
Commit and push the directory to a Git repository.
In your Developer Hub instance, register the documentation entity:
1. Click Catalog > Self-service > Register Existing Component.
2. In the Select URL box, enter the URL to the catalog-info.yaml file in your repository.
3. Click Analyze, then click Finish.

Verification

In the Developer Hub navigation menu, click Docs.
Verify that your standalone documentation appears in the table on the Documentation page.
Note
The documentation might not appear immediately. Developer Hub refreshes catalog entities periodically, which can take up to 45 minutes. To trigger a refresh sooner, navigate to the entity in the software catalog and click the refresh button on the Overview tab.

1.3. Enable documentation for an existing entity

You can add TechDocs documentation to a component that is already registered in the Developer Hub software catalog but does not yet have documentation configured.

Prerequisites

An existing entity is registered in the Developer Hub software catalog.
You have write access to the entity’s source repository.

Procedure

Add the backstage.io/techdocs-ref annotation to the catalog-info.yaml file in your repository:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-component
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: group:default/my-team

Create an mkdocs.yml file in the repository root:
```
site_name: My Component Documentation
nav:
  - Home: index.md
```
Note
Developer Hub automatically adds the techdocs-core plugin to mkdocs.yml if it is missing.
Create a docs/ directory in the repository root containing at least an index.md file with your documentation content in Markdown.
Commit, push, and merge the changes.

Verification

In the Developer Hub software catalog, navigate to your component.
Verify that a Docs tab appears with your documentation.
Note
The Docs tab might not appear immediately. Developer Hub refreshes catalog entities periodically, which can take up to 45 minutes. To trigger a refresh sooner, click the refresh button on the entity’s Overview tab.

2. Search for relevant content

To quickly find the information needed for your services, search or filter the TechDocs catalog. Narrowing your search helps you find relevant resources without browsing many repositories.

Procedure

In the Red Hat Developer Hub navigation menu, click Docs.
On the Documentation page, use the Search bar or filters to locate your document:
- Search: Enter keywords to find specific terms within documents.
- Filter by Owner: View documents owned by specific users or groups.
- Filter by Tags: Narrow results by specific labels or categories.
- Filter by Owned: View documents belonging to you or your group.
- Filter by Starred: View your bookmarked favorites.
  The results update automatically to show the number of documents that meet your criteria.

3. Access and navigate documentation

Use the built-in navigation tools to move between related documents within a book. This ensures you can easily reference implementation details and requirements in a logical sequence.

Procedure

In the Red Hat Developer Hub navigation menu, click Docs.
In the Documentation table, click the name of the document you want to view.
Navigate the content using the following on-screen tools:
- Search bar: Find keywords within the current document.
- Table of contents: Jump to specific sections.
- Navigation menu: Switch between different documents in the same book.
- Next: Proceed to the next sequential document.
- Add-ons: Perform additional actions if the system configures plugins, such as setting the text size.

4. Make changes to project documentation in TechDocs

You can edit a document in your TechDocs plugin directly from the document book page. Any authorized user in your organization can edit a document regardless of whether or not they are the owner of the document.

Procedure

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

5. Add video content to enhance TechDocs

You can use <iframe> elements to add video content to enhance your experience with 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:
```
<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.

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}

6. Streamline documentation builds using GitHub Actions

For production use, deploy TechDocs by building documentation in CI/CD, publishing to external storage such as AWS S3, and configuring read-only mode. You can automate this workflow using GitHub Actions to generate and publish TechDocs when users update documentation files.

Prerequisites

The TechDocs plugin is enabled and configured on your Red Hat Developer Hub 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 to store your TechDocs sites.
Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.
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.
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.
. In the navigation menu of the OpenShift Container Platform console, click ConfigMaps and select your RHDH app-config.yaml file.

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

Click Save.
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

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

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.