foreman-documentation

What the repository contains

The foreman-documentation repository stores the source material for the official Foreman and Katello documentation. Foreman is a lifecycle management tool for physical and virtual servers, and Katello adds subscription and repository management on top of it. This repository does not ship the software itself. Instead it collects the written guides that explain how to install, configure, and operate those systems. The content is authored in AsciiDoc, a plain text markup format suited to long technical manuals. The project follows the modular documentation framework that Red Hat developed, which splits topics into small reusable modules rather than monolithic pages. That structure lets the same concept be referenced from several guides without duplication. The repository is organized into a guides subdirectory for the AsciiDoc sources and a web subdirectory for the static site generator that powers docs.theforeman.org. A Vale style configuration lives inside the .vale directory so contributors receive automated feedback on wording and conventions. The repository also embeds agent skills for editors such as Claude and Cursor under the .claude directory, giving AI assistants project specific guidance when editing the docs. Beyond the two main projects, the repository documents a proof of concept effort to improve Foreman documentation and points contributors to the Foreman manual hosted at theforeman.org when they need the published reference for the core software. The web subdirectory README explains how to test the landing page locally, and the guides subdirectory README explains how to build individual guides, so a writer can work on one section without rendering the entire site.

How the documentation is built

A single Makefile at the repository root drives both the static site and the individual guides, which keeps local testing close to what runs in production. The html target compiles the AsciiDoc guides into HTML for every supported context, including foreman-el, foreman-deb, containerized-katello, containerized-orcharhino, katello, orcharhino, and satellite. The web target builds the landing page using the nanoc static site generator. The compile target gathers everything into a single result directory, and serve starts a local Python web server on port 5000 so contributors can review their changes in a browser. The PORT environment variable can change the port, with 5008 given as one example in the README. On modern multi core machines the build can run faster with the -j option, though the first full build is slow because every context is compiled. Stable versions are symlinked to the nightly build, and that can cause confusion if a guide was deleted or renamed upstream. Before building, the README asks contributors to install the gcc, gcc-c++, and ruby-devel packages so the toolchain is complete. The modular approach means a writer can rebuild a single guide locally without waiting for the whole site, which keeps the edit and preview loop short. GitHub Actions later validates links in the same HTML output, so the local build matches the checks that run on every merged change.

Contributing and deployment

Contribution begins with the project CONTRIBUTING file, which sets expectations about conventions, communication, and respectful collaboration across organizations. The Foreman community welcomes feedback, issues, pull requests, and reviews, and it explicitly notes that every contributor brings a different background and set of experiences. When a change is pushed to the master branch, GitHub Actions builds the HTML guides with link validation and the web artifact, then deploys them to the gh-pages branch if the build succeeds. Content for the current version lands under /nightly, while a tagged release such as X.Y is copied to its own path. The deployment process never deletes files on its own, so removing unwanted content requires a manual delete and push to gh-pages. When a new Foreman version is branched, the release owner creates a matching documentation branch and updates the shared attributes file with the new project and Katello versions, then notifies the documentation team on the Foreman Matrix chat channel. The documentation remains a living resource that tracks the software release by release, and the branching checklist in the README keeps that process repeatable for each new version of the product. Because the docs and the code share a release cadence, readers can trust that a guide for version X.Y describes the software they actually installed.

Editorial conclusion

The foreman-documentation project is published under the CC-BY-SA-4.0 license, and its web and HTML artifacts are rebuilt nightly from the master branch whenever a commit lands.