Red Hat Developer Hub documentation

This is a repository for Red Hat Developer (RHDH) documentation.

Contributing

Contribute to this repository to add new and edit existing RHDH documentation published on the Red Hat Documentation page.

Before submitting a pull request (PR), create a Jira issue associated with your contribution to this repository.

There are currently three Jira projects related to RHDH:

• RHDHBUGS - Red Hat Developer Hub Bugs.

• RHIDP - Red Hat Internal Developer Platform.

• RHDHPLAN - RH Developer Hub Planning.

Choose a Jira project that matches your contribution and create a new issue:

1. In the Jira project, click Create.

2. In the Description field, describe your contribution.

3. In the Component/s field, select Documentation from the drop-down list.

4. Save the created Jira issue.

Important

RHDH release notes are single-sourced from Jira. See the RHDH Release Notes process document and the release notes repository (VPN required) for details.

Style and formatting

All contributions are in AsciiDoc.

Make sure your writing follows the rules listed in IBM Style and Red Hat supplementary style guide.

Note	If the IBM Style and the Red Hat supplementary style guide offer conflicting solutions, the Red Hat supplementary style guide solution overrides IBM Style.

Follow the Modular documentation reference guide to modularize your content.

Building locally

Prerequisites

• Node.js

• Podman

• Vale

• Lychee (downloaded automatically by the build script if not installed)

• Optional for local builds: A GITHUB_TOKEN environment variable to avoid GitHub API rate limiting during lychee link validation. Use GitHub CLI (gh) to get and refresh the token: export GITHUB_TOKEN=$(gh auth token). This token is required in CI for deployment to gh-pages.

Procedure

1. Sync the Vale style rules:

   $ vale sync

2. Build HTML with images in titles-generated/ using ccutil in a container, then run lychee link validation and CQA content quality checks:

   $ ./build/scripts/build-ccutil.sh

   The ccutil CLI tool reproduces the behavior of the production publication chain (Pantheon), including its limitations, and is therefore preferred over asciidoctor.

Results are written to build-report.json.

Checking for broken links

The build command above includes lychee link validation automatically. To run lychee separately on already-built HTML:

Prerequisites

• Lychee

• Optional: A GITHUB_TOKEN environment variable to avoid GitHub API rate limiting. Use GitHub CLI (gh) to get and refresh the token: export GITHUB_TOKEN=$(gh auth token)

Procedure

1. Run lychee on the built HTML:

   $ lychee titles-generated/

To check for broken links in the published RHDH docs, use linkchecker:

Prerequisites

• linkchecker

Procedure

1. Run the following command to create a .txt file with a list of detected broken links:

   $ linkchecker --check-extern --output failures --file-output failures/broken-links.txt https://docs.redhat.com/en/documentation/red_hat_developer_hub/<version>

Previews

You can view commits to this repo as GitHub Page content here:

https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/

PRs have a link to the generated HTML attached as a comment.

The publication workflow has two stages:

1. The PR workflow and GitHub Pages workflow build HTML from AsciiDoc sources and push the output to the gh-pages branch using build/scripts/deploy-gh-pages.js, which handles concurrent pushes with automatic retry, cleanup of stale PR/branch directories, and index regeneration.

2. The GitHub Pages build and deployment workflow, managed by GitHub, detects pushes to the gh-pages branch and publishes the content to GitHub Pages.

See GitHub Publication Workflow Architecture for the full technical reference.

Reviews

All PRs are reviewed for technical accuracy by an SME and writing quality by another tech writer.

When possible, request a tech review first and implement suggestions from the SME. After your PR is approved by the tech reviewer, follow it up with a request a peer review.

Check this doc for the current peer review roster.

Merging PRs

After the peer and tech reviewer approve your PR, the PR is ready for merging and cherry-picking by a gatekeeper.

Check this doc for the current gatekeeper roster.

Labels

As you work on your contribution to this repo, use labels to show the status of your PR and to request reviews:

• draft: do-not-merge/work-in-progress

• ready for peer and technical reviews: do-not-merge/review-in-progress

• request for a tech review: technical-review-needed

• completed tech review: technical-review-done

• request for a peer review: peer-review-needed

• completed peer review: peer-review-done

• ready for merging: ready-to-merge

Note	Remember to remove labels as they become outdated. For example, remove the do-not-merge/work-in-progress label when you finalize your draft and your PR is ready for review.

Publishing pipeline

This repo is the upstream mirror of the GitLab RHDH repo https://gitlab.cee.redhat.com/red-hat-developers-documentation/rhdh

Merged PRs are synced to GitLab for build with Pantheon.

Plugins Reference Guide

For Plugin configuration guide, see upstream content in https://github.com/janus-idp/backstage-plugins/tree/main/plugins

Additional sources

• RHDH documentation contributor guide

• link:https://spaces.redhat.com/spaces/RHDEVDOCS/pages/494635174/Content+creation+guidelines [RHDH content creation guidelines]

• RHDH GitHub labels