theforeman/foreman-documentation: Building the Foreman and Katello Manuals Locally

What the Foreman documentation repository actually contains

The README is blunt about the scope: this Git repository contains the official documentation for the Katello project and a proof of concept for improving Foreman documentation, with progress tracked in a GitHub milestone. The official Foreman manual itself still lives at theforeman.org/manuals/latest. That split matters. If you came here expecting the Foreman smart-proxy code, the installer or the Katello server, you are in the wrong repository. What you get is the writing: AsciiDoc sources under guides/, a generated static landing page under web/, a hammer_cli_reference/ directory, and the tooling that turns all of it into HTML.

The intended audience is narrow and specific. People who file documentation issues, contributors who send pull requests against the manuals, translators, and release owners who have to branch a documentation set for a new Foreman version. The README states that the community welcomes feedback, issues, pull requests and reviews, and that contributors have different backgrounds and levels of experience with Foreman. The guidelines exist to set expectations and conventions across those groups. This is not a repository you clone to run Foreman. It is the repository you clone to change what the Foreman manual says.

AsciiDoc sources, a nanoc landing page, and one Makefile over both

The guides are AsciiDoc files organized around the modular documentation framework from Red Hat, which is why you find a guides/common/ directory holding shared attribute files rather than one flat book per product. Version numbers and product names are attributes, not literals: guides/common/attributes.adoc carries ProjectVersion, KatelloVersion, DocState and ProjectVersionPrevious. Changing a release means editing that file, not grepping the prose.

The build has two halves. The web/ subdirectory is a static site generated by nanoc, and the README notes it is always built from the master branch. The guides/ subdirectory produces the HTML manuals. The root Makefile stitches them together with targets named html, web, compile and serve. The html target fans out into seven contexts: foreman-el, foreman-deb, containerized-katello, containerized-orcharhino, katello, orcharhino and satellite. That means a full local build compiles the same content several times with different attributes, which is exactly why the README warns the initial build might be slow and suggests the -j option on multi-core machines. The Makefile sets MAKEFLAGS += -j by default and compiles the shared CSS once up front, because the comment in the file says parallel build processes would otherwise race on the same output file.

Deployment is handled by GitHub Actions. When a commit lands on master, all artifacts are built, the static site is copied into / and the HTML into /nightly, and the result is pushed to the gh-pages branch. When a commit lands on an X.Y branch, the HTML artifact is copied into /X.Y. The README is explicit that deployment does not delete files, so removing unwanted content from the published site requires a manual deletion and push into gh-pages.

Installing the toolchain and serving the manuals on localhost:5000

The README gives the prerequisites directly: install the gcc, gcc-c++, and ruby-devel packages before using the Makefile. The repository also ships a Dockerfile based on quay.io/fedora/fedora:44 that installs the development tools group, linkchecker, redhat-rpm-config, rubygem-bundler, and a pinned set of gems including asciidoctor-tabs, kramdown-asciidoc, nokogiri and sass. Pinning those versions is a sensible choice for a documentation build that has to stay reproducible across release branches.

With Ruby and the compilers in place, the default target builds everything and serves it. The README says to run make serve and open http://localhost:5000.

make serve

The Makefile shows what happens underneath: serve depends on nothing, so you need to have run a build first, or run compile, which builds the web site and the HTML guides and copies them into ./result. The port is a Makefile variable named PORT, defaulting to 5000, and the README documents how to change it.

PORT=5008 make serve

That serves the same directory on a different port. For a faster build on a multi-core machine, the README points at the -j option, which the Makefile already enables by default through MAKEFLAGS. If you only want the guides and not the landing page, the html target is the narrower entry point, and the guides/README.md covers building an individual guide on its own.

Branching a release and the symlink trap in stable versions

The release process is documented step by step, and it is the part most likely to break if done out of order. When a new Foreman version is branched, the release owner creates an X.Y branch from master, then on that branch sets DocState to RC and sets ProjectVersion and the matching KatelloVersion in guides/common/attributes.adoc, pushes, and notifies the documentation team on the Matrix channel. Back on master, ProjectVersionPrevious is updated to X.Y, a copy of web/releases/nightly.json becomes X.Y.json with state set to RC and the katello version corrected, the new version is added to .github/PULL_REQUEST_TEMPLATE.md, and VERSION_LINKS in the root Makefile is updated.

That last step is where the documented trap sits. The compile target loops over VERSION_LINKS and creates a symlink from each version directory to nightly. The README states plainly that stable versions are symlinks to the nightly (current) version, which can cause issues for deleted or renamed guides. In practice that means a page that exists in nightly but was removed or renamed in an older release can still resolve through the symlink, so a local build is not a reliable way to confirm that an old version's guide set is intact. Anyone verifying a stable release should check the deployed /X.Y directory rather than trusting the symlinked local result.

Vale rules, agent skills, and where this repository is the wrong tool

Style enforcement is built in. The repository uses the Vale linter, and .vale/styles/ contains a project-specific foreman-documentation style package with rules for Foreman documentation conventions. The README adds a constraint that is easy to miss: when adding a new rule to that style, make sure it does not duplicate the other styles already included in .vale/styles/. There are also two Vale configuration files at the root, .vale.ini and .vale-dita.ini, which suggests the same style set is applied to more than one document model.

The repository also carries a .claude/ subdirectory with skills for AI agents usable with Claude or Cursor, and the README invites contributors to add their own skills. That is unusual for a documentation repo and worth knowing before you wonder why agent configuration sits next to AsciiDoc sources.

Where this is the wrong tool: if your goal is to install Foreman or Katello, read the published manual, not the source. The README itself redirects to the Foreman Manual for official documentation, and the Katello content here is documentation, not the Katello application. Equally, if you want a single-page PDF of the manual, nothing in the repository description promises a PDF build target; the Makefile targets are html, web, compile, serve, toc and clean, and the Dockerfile installs linkchecker and asciidoctor rather than any PDF toolchain. The guides/README.md is the place to check what a single guide build produces.

How this differs from the Foreman manual site and from a wiki

The obvious alternative is the published Foreman Manual at theforeman.org/manuals/latest, and the difference is not cosmetic. The manual is the rendered output; this repository is the input plus the pipeline. If you only need to read about Foreman, the website is faster and always current with whatever was last deployed. If you need to change a sentence, fix a broken link, add a Katello procedure, or translate a guide, the website gives you no path and this repository does. The README frames the project as a proof of concept for improving Foreman documentation, which is an honest description of a repository that is mid-migration rather than a finished replacement.

A wiki is the other comparison worth drawing, and the mechanism differs sharply. A wiki page is edited and live in one step. Here, a change goes through AsciiDoc sources, a modular documentation structure with shared attributes, a Vale lint pass, a GitHub Actions build that validates links, and a push into gh-pages. That is slower for a one-line correction and considerably safer for a manual that ships with multiple product versions, because the version branching procedure and the attribute files keep the seven build contexts consistent instead of relying on editors to remember which page belongs to which release.

Editorial conclusion

Adopt this repository if you write, translate or review Foreman and Katello documentation, or if you need the manuals offline; skip it if you are looking for the Foreman installer or the Katello server code, which live elsewhere. Before contributing, run make serve, read CONTRIBUTING.md, and check that your Vale rules do not duplicate the styles already in .vale/styles/.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository