openshift-docs is the AsciiDoc source behind docs.openshift.com

One source tree serving four product variants

The openshift/openshift-docs repository holds the OpenShift 3 and 4 product and community documentation, and the README opens with the set of products it serves.

The four are OKD, the open source distribution, OpenShift Online, OpenShift Container Platform and OpenShift Dedicated. The README links the documentation site for each, and says that all OpenShift documentation is sourced in AsciiDoc and transformed into HTML, CSS and other formats through automation that is based on Asciidoctor. The published result is at docs.openshift.com.

Serving four products from one source tree is the central design decision, and it explains most of the machinery in the repository. If each product had its own documentation set, the divergence between them would be a permanent maintenance cost. Sharing one source means a correction to a procedure lands in every product at once, and it also means the content has to be written so that it can be filtered per product, which is what those machinery directories at the root are for.

The audience for the repository splits in two. The first group is anybody who wants to read the documentation, and for them the published site is the thing, not the repository. The second group is anybody who wants to change it, and for them this tree is the working copy. The README is written for the second group: it points to the contributing resources, gives a table of quick links for the first questions a newcomer asks, and gives a contact address for questions about the documentation itself.

The primary language of the repository is HTML, which reflects the output rather than the input, and the topics are documentation, hacktoberfest and openshift.

AsciiDoc in, Asciidoctor out, and a pipeline you do not run by hand

The build story is short enough to state in one sentence and complicated enough to need a directory of its own.

The source is AsciiDoc, and the transformation to HTML, CSS and other formats happens through automation based on Asciidoctor. The Makefile at the root has exactly one target, and it is not a documentation target:

all:
	./_update_rest_api.py

So the top level make target refreshes the REST API reference, and everything else is driven by other tooling. The Python scripts at the root give the shape of the pipeline: _update_rest_api.py, build.py and build_for_portal.py, plus a set of shell helpers for repository maintenance, autocomment.sh, automerge.sh, autopreview.sh and create_sum_link.sh.

There is a Ruby toolchain too, with a Gemfile, a Rakefile, a Guardfile and a _gemfiles/ directory, and the Rake tasks are the usual Ruby documentation pipeline. The Guardfile is a file watcher for live preview while editing, and the .gitpod.yml and .devcontainer/ directories provide a ready made editor environment, which is how a contributor ends up with a working toolchain without installing anything by hand.

And there is a container image for it, built from the Red Hat UBI minimal base:

FROM registry.access.redhat.com/ubi8-minimal:latest

ENV LANG=en_US.UTF-8

WORKDIR /go/src/github.com/openshift/openshift-docs

CMD ["/bin/bash"]

The work directory mirrors the Go import path of the repository, and the default command is an interactive shell, so the image exists to give you a working environment rather than to publish anything.

The Python requirements are equally minimal:

./aura.tar.gz
lxml~=4.9.1
pyyaml~=6.0
requests>=2.32.4

The first line is not a package but a vendored archive, which tells you that part of the toolchain is shipped inside the repository rather than installed from an index.

Dozens of topic directories, and a set of underscore directories

The root listing is the best available map of the documentation, and it divides cleanly into two kinds of entry.

The first kind is the content, one directory per subject area. You can see adding_service_cluster, admission-config.yaml, ai_applications, ai_workloads, api-config.yaml, applications, architecture, authentication, backup_and_restore, cicd, cli_reference, cloud_experts_osd_tutorials, cloud_experts_tutorials, contributing_to_docs and disconnected in the visible part of the listing, and the list continues well past what the excerpt shows. Each is a topic tree, and the yaml files at the root of the listing are single documents that sit alongside them.

The second kind is the machinery, and each of these directories carries a leading mark in its name. There is _attributes, _converters, _gemfiles, _images, _javascripts, _stylesheets, _templates and _topic_maps, plus _distro_map.yml at the root. That leading mark is the convention that keeps the publishing templates and shared assets from being mistaken for content, and _distro_map.yml is the file that says how the content maps onto the product variants.

The split is worth understanding because it tells you where a change goes. If you are adding a procedure, it goes in a topic directory. If you are changing how a page is rendered, or adding a shared attribute, it goes in one of the machinery directories. And if you are adding a page that only applies to one product, the distro map is where you express that.

For a reader who wants to know how a large platform documents itself, the tree is a catalogue of the platform's surface area, ordered the way the documentation is meant to be navigated.

Four documents answer the four questions a newcomer asks

The contributing section of the README is a table with one row per question, and it points into the contributing_to_docs directory each time.

If you are interested and want to contribute, the answer is the contributing topic, which explains the repository and how you can contribute. If you want the basic guidelines, the documentation guidelines topic gives the rules that keep the content consistent, and includes other style information. If you want to set up your workstation, the tools and setup topic covers it. And if you want to edit an existing topic or create new content, the create or edit content topic gets you started.

Four documents, in the order a newcomer asks the four questions. It is a small piece of documentation design that is worth copying.

The guidelines topic matters most for a contributor, because the consistency problem in a documentation set this size is not about the technology, it is about voice, structure and terminology. A rule that a procedure uses one heading level, or a term list that says which name to use for a concept, is the kind of thing that keeps four product variants from drifting into four different descriptions of the same feature.

The README also notes that the text of the contributing section is mirrored in the CONTRIBUTING.adoc file at the root, with a comment instructing that if you update one you update both. That is a small trap for a first contribution, and the kind of detail that is easier to read in the source than to discover in a pull request review.

Vale, gitleaks and yamllint are the guard rails

Three configuration files at the root tell you what a contribution has to survive.

.vale.ini with a .vale/ directory is the style checker, and for a documentation set the style checker is not cosmetic, because the alternative is a reviewer reading every sentence. Vale runs against the prose and enforces the vocabulary and phrasing rules that the guidelines describe, which means the mechanical part of consistency is checked by a tool and the judgement part is left to the reviewer.

.gitleaks.toml is the secret scanning configuration, which in a repository with an enormous number of configuration examples is doing real work. Documentation for a container platform is full of command lines with credentials in them, and a secret scanner that runs on the repository is what keeps an example password from becoming an incident.

.yamllint is the YAML linter, and there is a lot of YAML in an OpenShift documentation set, in the examples that are the most copied part of any product documentation. There is also a .ci-operator.yaml, which is the configuration for the Red Hat CI operator, and .s2i/ for source to image.

Together these describe a contribution pipeline that treats documentation as engineering. The prose is linted, the examples are linted, the secrets are scanned, and the preview is generated automatically through the autopreview.sh script, with automerge.sh handling the merge step and autocomment.sh leaving feedback on the pull request.

Licence, contact and the state of the tree

The licence is Apache-2.0, with the LICENSE file at the repository root, and the repository is not archived. The last push was on 2026-10-20, and the repository publishes no GitHub releases, which is the correct shape for a documentation source where the output is the published site rather than a versioned artefact.

The contacts section is short. For questions or comments about the OpenShift documentation, the README says to send an email to the OpenShift documentation team at [email protected].

Two housekeeping artefacts at the root are worth knowing about. There is an OWNERS file, which is the mechanism by which the Kubernetes style project assigns review responsibility per path, and a NewPSC.png at the root, which is a graphic asset rather than a code dependency. There are also 404-commercial.html and 404-community.html, the error pages served for the two variants of the site, which is a small illustration of the split between the commercial and community documentation streams.

For a reader evaluating the project as a model, the takeaways are these. The content is in one place and published to four products. The pipeline is AsciiDoc plus Asciidoctor plus a Ruby toolchain plus a small Python helper set, and the developer environment is a container image or a devcontainer so that a contributor is not the person who installs the toolchain. The style is enforced by a linter, the examples by another, and the secrets by a third. And the entry point for a newcomer is four documents, one per question they are likely to have.

Editorial conclusion

Adopt openshift-docs as the authoritative source if you maintain OpenShift documentation, want to check how a Red Hat platform documents a feature before writing your own, or want to contribute an upstream fix to the official docs. Do not adopt it as a general documentation framework, because the structure, the Vale rules and the product specific terminology are built for one product family, and the build automation is tied to that publication pipeline. Before you contribute, read the four contributing topics, run the documentation guidelines check with Vale on the files you touched, and check the compile output for the specific product variant you changed, because the same source is published for OKD, OpenShift Online, Container Platform and Dedicated.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. openshift/openshift-docs on GitHub
4. Project website
5. README