Open-source project
theforeman/foreman-documentation avatar
theforeman/foreman-documentation

foreman-documentation: two build pipelines, seven guide contexts, one gh-pages branch

Documentation for the Foreman Project and its ecosystem

27 stars126 forksSCSSCC-BY-SA-4.0

At a glance

What is it?
The repository behind docs.theforeman.org holds Katello documentation as AsciiDoc guides and a nanoc static site for the landing page, built separately and merged by a root Makefile into a result directory full of symlinks. Deployment copies artifacts into gh-pages and never deletes, and cutting a release touches attributes.adoc from both sides.
Who is it for?
Use it when you are writing or reviewing Foreman or Katello documentation, or when you want to preview a guides change without a full site build. It is not the place to look for the official Foreman manual, which lives elsewhere and is pointed to from here, and the proof-of-concept framing means this repository is not the finished documentation.
Can I use it commercially?
Yes, with credit. CC-BY-SA-4.0 allows commercial use as long as you credit the authors and indicate what you changed. It is written for creative content, so check how it applies to any code.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly SCSS, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • theforeman/foreman-documentation27 ★ · +2
Star history
Repository2026-08-242026-11-15
theforeman/foreman-documentation2527

2 Stars in the last 83 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Guides are AsciiDoc, the landing page is nanoc, and they never share a build

Two independent pipelines live in this repository. The `guides/` subdirectory holds the documentation sources as AsciiDoc files, structured on the modular documentation framework, and each guide can be built on its own using the instructions in `guides/README.md`. The `web/` subdirectory holds the sources for the docs.theforeman.org landing page, built as a generated static site with the nanoc tool, and the static content is always built from the `master` branch. `web/README.md` is also where local testing of the site is described, which matters because the release procedure calls back into it. Keeping them apart means a landing page edit and a guide edit do not invalidate each other, and it is why the root Makefile has to stitch the two output trees together afterwards.

make html serve builds all seven contexts before serving anything

The root Makefile target that most contributors run is two words:

code
make html serve

Then the site is at `http://localhost:5000`, and `PORT=5008` moves the port, with 5000 as the default. The `html` target is not one build: it depends on `build-foreman-el`, `build-foreman-deb`, `build-containerized-katello`, `build-containerized-orcharhino`, `build-katello`, `build-orcharhino` and `build-satellite`, so all seven documentation contexts are rendered before anything is served. Since building every context is slow, the documented fast path is a single variant:

code
make build-foreman-el serve

The `serve` target itself is one python3 invocation, `python3 -m http.server --directory ./result $(PORT)`, and it is the default target of the Makefile. Before any of this you need the `gcc`, `gcc-c++` and `ruby-devel` packages installed.

Twenty-three version numbers become symlinks pointing at nightly

The `compile` target merges the nanoc output and the guides output into a single directory called `result`, with the site at the top and the guides under `result/nightly`. Then every version in `VERSION_LINKS` becomes a symlink to `nightly`:

code
	for V in $(VERSION_LINKS); do ln -sf nightly $(DEST)/$$V; done

`VERSION_LINKS` currently runs from 5.0 down through the 3.x series to 2.4. The consequence is documented rather than hidden: stable versions are symlinks to the nightly version, which can cause issues for deleted or renamed guides, because every historical URL is showing the same directory and removing a file removes it from every version at once. Two other details are worth noting if you build on Windows or macOS. The copy switches from `cp -l` on Linux to a plain copy on Darwin, detected from `uname`, since hard links behave differently there.

The Dockerfile pins every gem, on Fedora 44

The container is built from `quay.io/fedora/fedora:44` with the `development-tools` group installed, plus `gcc-c++`, `linkchecker`, `redhat-rpm-config`, `ruby-devel` and `rubygem-bundler`. The gems are then installed at exact versions rather than resolved: asciidoctor-tabs 1.0.0.beta.6, ffi 1.17.4, kramdown-asciidoc 2.1.1, nokogiri 1.19.4, racc 1.8.1, rb-fsevent 0.11.2, rb-inotify 0.11.1, sass-listen 4.0.0 and sass 3.7.4, and the build ends by printing the Asciidoctor version. The working directory is `/foreman-documentation/guides`. `linkchecker` is the package that makes the link validation stage in the GitHub actions workflow possible, and sass explains why the repository's primary language shows up as SCSS. Two file-watcher gems, rb-fsevent and rb-inotify, are there for local rebuild-on-save, and sass-listen is what consumes them.

Vale checks conventions through a project style package

Style is enforced by the Vale linter, configured through `.vale.ini` and `.vale-dita.ini` at the root. The rules live in `.vale/styles/`, which contains a project-specific `foreman-documentation` style package holding rules that check Foreman documentation project conventions, sitting alongside the styles Vale ships with and any others included. The one instruction given for contributors working on it is a duplication constraint: when adding a new rule to the `foreman-documentation` style, make sure it does not duplicate the other styles included in `.vale/styles/`. That ordering matters, because a rule that already exists in an included style will either never fire or will fire twice depending on which one wins, and neither outcome is what the contributor intended.

Deployment copies into gh-pages and never deletes

GitHub actions build two artifacts, HTML with link validation and the WEB static site, and only if they succeed and the branch is `master` or stable are the artifacts downloaded, extracted and committed into the `gh-pages` branch. On `master`, the static site and the HTML are copied into `/` and `/nightly` respectively. On a version branch `X.Y`, only the HTML artifact is copied, into `/X.Y`. The behaviour that trips people up is stated plainly: deployment does not delete files, so to remove unwanted content from the published site, manual deletion and a push into `gh-pages` has to be performed. That means a deleted guide file keeps its published page until somebody cleans it up by hand.

Cutting a release edits attributes.adoc from both branches

Branching a new release is a procedure with a master side and an `X.Y` side, and the release owner runs it. On `master` you pull the latest changes and create the `X.Y` branch. On `X.Y` you update `guides/common/attributes.adoc`, setting `DocState` to `RC`, setting `ProjectVersion` to `X.Y` and the matching `KatelloVersion`, then push and notify the doc team on the TheForeman Doc Matrix channel. Back on `master` you set `ProjectVersionPrevious` to `X.Y` in the same file, copy `web/releases/nightly.json` to `X.Y.json` and set its `state` to `RC` with `katello` moved to the right version, deploy the website locally to test, add the new Foreman version to `.github/PULL_REQUEST_TEMPLATE.md`, and update `VERSION_LINKS` in the root Makefile. The check at the end is that the links and landing page appear correctly and the HTML guides land in `/X.Y`.

Agent skills live in .claude, and licensing is per subdirectory

The repository carries skills for AI agents under `.claude/`, usable with Claude or the Cursor editor, and contributors are invited to add their own skills for the work they do on the documentation, with more detail pointed at AgentSkills.io. Alongside that, the root holds `hammer_cli_reference/`, `scripts/`, `generate-authors`, `AUTHORS`, `.mailmap`, `.editorconfig`, `.vscode/`, `Gemfile`, `index.html` and `.dockerignore`. Licensing is worth reading twice: the repository is published under CC-BY-SA-4.0, and the README sends you to the LICENSE files in the respective subdirectories for the terms that actually apply. On content, this repository holds the official Katello documentation and a proof of concept for improving the Foreman documentation, tracked on a milestone, while the official Foreman documentation is the Foreman Manual at theforeman.org.

Editorial conclusion

Use it when you are writing or reviewing Foreman or Katello documentation, or when you want to preview a guides change without a full site build. It is not the place to look for the official Foreman manual, which lives elsewhere and is pointed to from here, and the proof-of-concept framing means this repository is not the finished documentation. Before contributing, read CONTRIBUTING.md, check that a rule you add to the foreman-documentation Vale style does not duplicate an existing one, build a single variant with make build-foreman-el serve rather than the full context set, and remember that published content on gh-pages is copy-only, so removing a page needs a manual delete and push.

Frequently asked questions

What does foreman stand for?

The README does not expand the name. It describes this repository as holding the official Katello documentation and a proof of concept for improving the Foreman documentation, tracked on milestone 3, with the official Foreman documentation kept separately in the Foreman Manual.

Is foreman a supervisor?

Not as described here. This is a documentation repository, and the products it documents appear as build contexts: foreman-el, foreman-deb, katello, orcharhino, containerized-katello, containerized-orcharhino and satellite. Nothing in the README describes a process supervisor.

How do I preview foreman-documentation changes locally?

Install the gcc, gcc-c++ and ruby-devel packages, then run `make html serve` and open `http://localhost:5000`, using `PORT=5008` for a different port. Building all seven contexts is slow, so `make build-foreman-el serve` builds a single variant instead.

Why does a deleted foreman guide still appear on an older version page?

Because the compile target makes every version in `VERSION_LINKS` a symlink to the nightly directory, which the README notes can cause issues for deleted or renamed guides. Publishing also never deletes files, so removing a page from the deployed site needs a manual deletion and push into gh-pages.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/theforeman-foreman-documentation.svg)](https://hysenlabs.com/projects/theforeman-foreman-documentation)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/theforeman-foreman-documentation.svg)](https://hysenlabs.com/projects/theforeman-foreman-documentation)

Was this useful?