centos / docs

CentOS Documentation project.

CentOS Docs website builder

This repository hosts the site builder for https://docs.centos.org/. It pulls content from other repositories defined in the site.yml Antora playbook, builds them together using a structure defined in this repository, and applies a UI bundle to them, creating the whole site. Submit PRs and issues to this repository for publishing fixes. The other repositories are:

• CentOS_Docs_Web_UI for the site's user interface (e.g. CSS styling) sources
• CentOS_Installation_Guide - the content repository for the Installation Guide
• CentOS_Docs_Web - the repository that holds the built site. Do not use that repository for anything but publishing updates.

Adding new content

To add a new content repository, you must:

1. Add the repository to the site.yml file. Use the repositories already defined for guidance.
2. Add a link to the front page of the new repository into pages/homepage/modules/ROOT/pages/index.adoc. Note that you will need to do this in raw HTML, the page uses a passthrough block. Again, use the other links already on the page for guidance.
3. Build this repository and publish - see below.

Local preview

This repo includes scripts to build and preview the contents of this repository. Both scripts use docker, so please make sure you have it installed on your system. Please see below for instructions.

To build and preview the site, run:

$ ./build.sh && ./preview.sh

The result will be available at http://localhost:8080.

Installing docker on Fedora

$ sudo dnf install docker
$ sudo systemctl start docker && sudo systemctl enable docker

How to publish

1. Build the site using the build.sh script.
2. Open the CentOS_Docs_Web and switch to branch prod.
3. Copy the public/ folder of this repository into the en-US folder of the docs-web repository.
4. Ask someone to pull from the repository and republish. (In the future this will happen automatically, this is only a temporary workaround.)

docs's Issues

Review lorax chapter

The chapter on Lorax is probably not fully accurate since it was taken directly from RHEL7 and it references some RHEL-specific workflows. Determine how this works on CentOS and adjust for any differences.

Removing the s390/system Z part

We don't have a s390/system Z architecture port so it should be removed from the doc to not confuse people about upstream arches not covered on our side
Also then wondering about the other arches we support but that aren't in the doc (aarch64/armhfp)

Convert for Antora

Convert the Installation Guide to work with the Antora publishing system. This will require a significant change in the book's structure, fixing links, and setting up some scripts so we can build it.

Rewrite the Downloading chapter

The chapter on downloading images currently talks about how to get isos from the Red Hat customer portal. It should instead cover what's available at https://www.centos.org/download/.

Ensure no links to redhat.com go behind a paywall

The guide currently contains multiple links to access.redhat.com. Most of them are to un-paywalled RHEL7 guides, but some are to the Knowledgebase which probably has a paywall. Those should be replaced with equivalent non-paywalled content or removed.

Deep-linking past the access.r.c paywall

Chapter 26 contains a link that deep-links past the access.redhat.com paywall to https://access.redhat.com/labs/rhelupgradehelper/ which doesn't look kosher.

Wipe revision history

The current asciidoc version of the book contains revision history from the RHEL guide. We should get rid of that.

Fix other product mentions

In several places the book refers to other Red Hat products such as Satellite, RHEL Atomic Host, or RHEV. We should identify the upstream for each such product and refer to that instead.

Fix iso names

In a lot of places the guide references ISO images and uses the Red Hat format for their filenames. This should be changed to the format CentOS uses.

Ensure architecture-specific information is correct

There are some arch-specific parts in the book, mentions of ppc64 BE/LE, specific architecture limitations, etc. These are taken directly from RHEL so they need to be reviewed to ensure they apply to CentOS.

There is no CentOS Upgrade Tool that works

The entire section on using the CentOS Upgrade Tool needs to be removed; the tool does not work.