Fedora Docs Build Repository

Warning

This is an experimental repository for testing.
Expect force pushes and rebases.

This is the build repository for the Fedora Documentation Website. Fedora Docs are built using Antora. The repository CI builds the following container images:

• quay.io/fedora-docs/buildroot:latest
  The image is built daily and is used in the Fedora Forge runner to build the other images.

• quay.io/fedora-docs/antora:latest
  The image is built daily. It contains the Antora application and is used in the docsbuilder.sh script.

• quay.io/fedora-docs/fedocs:latest
  The image is built on push/PR and daily. It bundles fedocs.py, the watch/build/preview tool for a single Fedora Docs component repo — see Previewing a single component.

• quay.io/fedora-docs/fedocs-cache:latest
  The image is built hourly. It's not a runnable tool, just prefetched clones of every Fedora Docs component, mounted alongside fedocs at preview time so a fresh checkout doesn't need to clone ~50 repos on startup.

• quay.io/fedora-docs/council-docs-test:latest
  The image is built hourly. It contains the generated English Fedora Docs site and can be previewed by following the instructions in the Previewing the site section.

Prerequisites

• Podman (for container operations)
• just (command runner)

Verifying images

The images are signed using Cosign and can be verified by running the following command:

just verify-image quay.io/fedora-docs/antora:latest

To verify another image, replace quay.io/fedora-docs/antora:latest in the above command with any other image in the Fedora Docs organization.

Scanning images

To scan images for vulnerabilities using Grype, run the following command:

just scan-image quay.io/fedora-docs/antora:latest

To scan another image, replace quay.io/fedora-docs/antora:latest in the above command with any other container image.

Testing changes locally

Building the site

The following command builds the English documentation container image using the specified playbook file (defaults to site.yml).

just build-site ./site-council-docs-test.yaml

Note

Rebuilding all the languages locally may take hours and result in a large container image.

Note

The container build process uses multiple build stages, which can leave behind dangling images on your system. To clean these up, run:

just cleanup-images

The above command removes unused images and build cache, then displays the first 21 images on your system.

Previewing the site

The following command runs the built container image and exposes the documentation site at http://localhost:8080 for local testing.

just preview-site

Previewing a single component

A single component repo (e.g. council-docs-test) doesn't need this repo's own build-site/preview-site — it pulls the already-published fedocs/fedocs-cache images instead. From that repo:

just preview-components

This runs a live watch/rebuild preview server against the real, full cross-component playbook (every other Fedora Docs component already prefetched into fedocs-cache), so xrefs into other components resolve correctly from the first build. fedocs/fedocs-cache themselves are only built here, via:

just build-fedocs
just build-fedocs-cache

build-fedocs-cache defaults to prefetching the real site.yml; pass ./site-council-docs-test.yaml explicitly to match what the published, CI-built image (and council-docs-test's own preview) actually uses.

Per-PR previews

A component repo can also publish a live preview automatically on every pull request, via its own .forgejo/workflows/pr-preview.yaml (see council-docs-test for a working example) — built on top of the same fedocs/fedocs-cache images, published to a shared host. See this repo's CLAUDE.md ("PR preview pipeline for component repos") for how that pipeline actually works and the infrastructure it depends on.

Documentation content

Documentation content is stored in multiple repositories listed in the site.yml file.

Project Plan

See the Project Board at the Documentation Team.

Reporting issues

Please report general issues and submit pull requests for publishing fixes here.

Contributing

Want to contribute? Learn about contributing to the Fedora Docs.