Documentation on Home

Mirroring Red Hat Documentation Locally with rh-mastery

Sat, 13 Jun 2026 00:00:00 +0000

Workflow diagram of rh-mastery process - AI generated

Introduction

In this post, I want to describe a tool built by my team mate Francisco J. Lopez Grüber that solves a problem most people quietly live with: Red Hat product documentation is comprehensive and well-maintained, but it lives on the internet. Accessing it requires a browser, a connection, and knowing where to look. For offline environments, air-gapped labs, or anything beyond casual browsing, that dependency quickly becomes friction.

rh-mastery addresses this directly. It mirrors Red Hat product documentation from docs.redhat.com as PDF files into a local directory tree, and optionally can convert those PDFs to Markdown. The Markdown output is where things get particularly interesting: combined with tools like qmd from Shopify CEO Tobias Lütke, the converted documentation becomes a local knowledge base that AI agents can query directly — no internet access required, no context switching, and no copy-pasting from browser tabs. For anyone building AI-assisted developer workflows, having structured access to accurate, version-tracked product documentation is a meaningful step up.

The tool is available on GitHub at flg-redhat/rh_mastery.

What rh-mastery Does

At its core, rh-mastery handles two tasks:

Sync: For a given product alias or slug, it probes docs.redhat.com, resolves the current documentation version, and downloads all available PDFs into a structured local directory tree: {download_base}/{slug}/{version}/.
Convert: Once PDFs are present, the convert command transforms them into Markdown files using PyMuPDF4LLM (default) or Docling as an optional heavier-weight alternative. Each Markdown file includes a short YAML front matter block with provenance metadata — title, source, version, and conversion timestamp.

Individual products can be targeted using short aliases such as --ocp or --ansible, or by passing the full Red Hat documentation slug directly. To download the complete documentation for all tracked products at once, rh-mastery sync --all handles that in a single invocation.

The recommended way to run rh-mastery is via its container image, which keeps dependencies isolated and makes the workflow reproducible.

Setting Up the Environment

The image is built from Red Hat Universal Base Image 10 Init and includes systemd, allowing for optional scheduled syncs via timers or cron inside the container. Build it from the repository root:

git clone https://github.com/flg-redhat/rh_mastery
cd rh_mastery
podman build -f Containerfile -t rh-mastery:latest .

Create a local data/ directory to hold the downloaded files. This directory will be mounted into the container, so its contents persist across container restarts and recreations.

mkdir -p data

The Workflow

The end-to-end workflow from a fresh image to a set of Markdown files ready for distribution follows five steps.

Start the container

podman run -d --name rh-mastery \
 --systemd=always --rm \
 -v ./data:/var/lib/rh-mastery:Z \
 rh-mastery:latest

This starts the container in detached mode and mounts the local data/ directory into /var/lib/rh-mastery inside the container. All downloads and converted files will appear under data/ on the host.

Open an interactive shell

podman exec -it rh-mastery bash

Sync the documentation

rh-mastery sync --all

This downloads the current documentation for all tracked products into the mounted volume. Individual products can be synced using their alias, for example rh-mastery sync --ocp or rh-mastery sync --ansible. Run rh-mastery --help inside the container to see the full alias table.

Convert PDFs to Markdown

rh-mastery convert --all

This converts every synced PDF into a Markdown file alongside it. Both the original PDFs and the converted Markdown files are present after this step. The conversion uses PyMuPDF4LLM by default, which handles most layouts well. For documents with complex tables or multi-column layouts, the --engine docling option is available but requires installing additional dependencies.

Exit the container and clean up PDFs (optional step)

Once conversion is complete, exit the container shell. Depending on the use case, the original PDF files may no longer be needed, if Markdown is the target format, removing the PDFs reduces the total size of the data directory significantly:

exit
find ./data/RHDocumentation -name "*.pdf" -delete

The Markdown files in data/RHDocumentation are now ready for local use, distribution, or ingestion by an AI agent.

From Markdown to AI Agent Knowledge

The Markdown output from rh-mastery is structured and annotated, which makes it well-suited for ingestion by AI agents and local language model tooling. Each file carries front matter metadata that allows agents to identify the product, version, and source, and the content retains the section hierarchy of the original documentation.

qmd, built by Tobias Lütke, is a lightweight tool for querying local Markdown files. Pointed at the directory tree produced by rh-mastery, it gives AI agents fast, accurate access to the full Red Hat documentation corpus, entirely offline and without relying on external APIs or web retrieval. The combination is particularly effective in environments where internet access is restricted, or when a development workflow benefits from a self-contained, version-locked knowledge source.

Conclusion

rh-mastery turns what would otherwise be an ongoing manual effort into a single repeatable command. The container image keeps the setup clean, and the Markdown output opens up practical AI-assisted use cases that go beyond what a standard documentation browser can offer. Francisco’s tool fills a gap that is easy to overlook until you actually need it.

References

rh-mastery - GitHub repository by Francisco J. Lopez Grüber - link
qmd - GitHub repository by Tobias Lütke - link
Red Hat product documentation - link

Enhancing Code Project Documentation through Automated Changelogs

Tue, 26 Mar 2024 00:00:00 +0000

This article was published on March 25, 2024, on opensourcerers.org:

Abstract

In the rapidly evolving landscape of software development, documentation of modifications and updates is crucial for maintaining project continuity and ensuring team alignment. This blog article introduces Conventional Changelog, a tool developed to address this very challenge. The tool transforms a project’s commit history into a detailed, readable changelog. Its adherence to the Conventional Commits and Semantic Versioning practices fosters a well-structured documentation that enhances transparency for users and contributors alike. Versatile by design, it integrates seamlessly into various deployment environments, from local IDEs to continuous integration pipelines like GitHub Actions and Tekton Tasks.

Motivation

As projects evolve, maintaining a clear history of changes becomes a challenge. Traditional methods often fall short, leading to overlooked updates or a cluttered changelog. The need for a solution that not only automates this process but also aligns with best practices in software development — such as Semantic Versioning and Conventional Commits — sparked the idea to develop the proposed tool. Conventional Changelog addresses this gap, offering a solution that is both comprehensive and easy to adopt, ensuring no code commit goes unrecorded.

The proposed approach integrates three foundational best practices to enhance a project’s documentation:

Semantic Versioning: This practice involves structuring version numbers as MAJOR.MINOR.PATCH. Each segment signifies the nature of changes: MAJOR versions indicate incompatible API changes, MINOR versions add features in a backward-compatible manner, and PATCH versions address backward-compatible bug fixes. This method provides a clear, incremental structure for versioning that reflects the scope and impact of changes.
Conventional Commits: Building on the idea of structured commit messages, this practice categorizes code changes to clearly communicate their intent. Based on the Angular Convention for code commits, valid categories are: feat:, fix:, build:, chore:, ci:, docs:, style:, refactor:, perf:, and test:. The proposed tool introduces additional categories such as deploy:, gitops:, and demo:. The motivation is to cover code changes of deployment files (e.g. Kubernetes manifests), code changes which trigger automated GitOps-driven deployments, code changes which are motivated by demonstration purposes. This ensures a well-organized commit history.
Keep a Changelog: Advocates for maintaining a changelog as a curated list of notable changes for each project version. It emphasizes structuring the changelog in a way that is accessible and informative for users, grouping changes by type and listing them chronologically. Including an “Unreleased” section helps to offer visibility into the latest code commit which might be part of upcoming software releases.

Together, these practices offer a comprehensive framework for managing software versioning, commit documentation, and changelog maintenance, making it easier for teams to navigate the complexities of project development and for users to stay informed about significant updates.

Executing the Script: A Multifaceted Approach

The tool can be operated in various ways. These methods are explained in more detail below. To avoid exceeding the scope, minimal examples for the individual options will be used. This flexibility allows developers to choose the best approach for their individual workflow, enhancing productivity and ensuring accurate documentation of project evolution.

Local execution

Conventional Changelog stands out for its adaptability, easily incorporating into the local development environment. Developers can execute the script directly, ensuring their changelog remains up-to-date with every commit.

./generate_changelog_local.sh

Alternatively, utilizing a container engine like Podman or Docker offers an isolated setup, guaranteeing consistent execution across different environments Independent of the underlying operating system.

First, build the container image using the provided Dockerfile. This step creates an image with the necessary environment to run the script:

podman build -t <image-name> -f Dockerfile

After building the image, run the container. This step mounts the current working directory into the container, allowing the script to access and update the changelog file within the project directory:

podman run -it --rm -v "$(pwd):/repo" <image-name> sh

Inside the container, navigate to the mounted repository directory and execute the script. This process generates the changelog within the containerized environment, reflecting the changes back to the local repository:

cd repo
./generate_changelog_local.sh

GitHub Action

Integrating Conventional Changelog into a CI/CD pipeline as a GitHub Action streamlines the process of keeping your changelog current and comprehensive. The configuration of the GitHub Actions workflow allows for the changelog generation to be initiated based on certain git operations, targeted branches, or through workflow dispatch, providing flexibility in how and when updates are documented.
The following GitHub Actions workflow example is designed to trigger the automatic generation of an updated changelog with every code push to the main branch. For this functionality to operate correctly, it’s necessary to adjust the GitHub workflow permissions to have both read and write access in the repository settings (Settings -> Actions -> General -> Workflow permissions).

YAML GitHub Action Workflow


name: Generate Changelog

on:
 push:
 branches: [ main ]

jobs:
 changelog:
 runs-on: ubuntu-latest
 name: Generate and Commit Changelog

 steps:
 - name: Checkout Repository
 uses: actions/checkout@v4

 - name: Generate Changelog
 uses: smichard/conventional_changelog@2.0.0
 with:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

 - name: Set Git User Info
 run: |
 git config user.name 'GitHub Actions Bot'
 git config user.email 'actions@github.com'

 - name: Commit Changelog
 run: |
 git add CHANGELOG.md
 git commit -m "docs: :robot: changelog file generated" || echo "No changes to commit"
 git push

This automation streamlines the maintenance of the project’s documentation, ensuring a real-time, accurate account of changes, fixes, and new features. It’s a seamless process that saves time and improves accuracy, crucial for projects with frequent updates.

Tekton Task

Conventional Changelog extends its versatility by offering seamless integration as a task within Tekton pipelines. This feature is particularly beneficial for users operating in Kubernetes and OpenShift environments, allowing for the automation of changelog generation as part of a deployment workflow.

Begin by applying the provided tekton/task_generate_changelog.yml configuration. This step enables using the provided Task as part of a Tekton Pipeline. Make sure to have the git-clone Task installed in your cluster:

oc apply -f tekton/task_generate_changelog.yml

Integrate the provided task into a Tekton pipeline. Find below a minimal pipeline configuration. This pipeline illustrates a minimal configuration which retrieves a Git repository and generates the changelog. However, the provided pipeline can serve as a blueprint to be adopted in a larger context. If the generated changelog file needs to be committed back to the repository, additional steps are required to handle the commit process:

yaml Minimal Tekton Task

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
 name: minimal-pipeline
spec:
 workspaces:
 - name: source
params:
 - name: git-url
 type: string
 description: "URL of the git repository"
tasks:
 - name: fetch-repository
 taskRef:
 name: git-clone
 kind: Task
 workspaces:
 - name: output
 workspace: source
 params:
 - name: url
 value: $(params.git-url)
 - name: revision
 value: "main"
 - name: generate-changelog
 taskRef:
 name: generate-changelog
 workspaces:
 - name: source
 workspace: source
 runAfter:
 - fetch-repository

Apply the pipeline:

oc apply -f tekton/pipeline

Integrating the solution as part of a Tekton pipeline, just as with a GitHub Action workflow, demonstrates the solution’s flexibility and ensures a timely and accurate record of changes, bug fixes, and new features.

Summary

In a dynamic software development world, maintaining an accurate and comprehensive project history is pivotal for team alignment and project continuity. The introduction of Conventional Changelog offers a robust solution to this challenge, transforming commit histories into detailed, structured changelogs. This tool marries the principles of Conventional Commits and Semantic Versioning with the best practices of changelog maintenance, ensuring a transparent and accessible documentation process. Versatile enough to integrate with local IDEs, containerized environments, GitHub Actions, and Tekton Tasks, Conventional Changelog streamlines documentation workflows, making it an essential tool for developers seeking to automate and enhance their project documentation practices. This post presented the motivation behind Conventional Changelog, outlined its background, and provided practical guidance on its multifaceted execution strategies, demonstrating its utility in modern software development environments.

References

GitHub Repository of Conventional Changelog - link
GitHub Action Marketplace - link
Semantic Versioning Specification - link
Conventional Commits Specification - link
Angular Commit Message Guidelines - link
Keep A Changelog Specification - link
Tekton Documentation - link
Documentation for the git clone Tekton Task - link