[CentOS-docs] Introducing the new docs site

Mon Oct 15 14:53:11 UTC 2018
Petr Bokoc <pbokoc at redhat.com>

Hi everyone,

as you might have noticed, we now have an actual docs site with an 
install guide: https://docs.centos.org/

It's very much a work in progress (I need to figure out how to get rid 
of the two navbars on the main page and a bunch of other things), but I 
believe even in the current state it's going to be useful to any CentOS 
users. The Installation Guide is adapted from the RHEL7 Install Guide, 
and I'll be looking at ways to get our own release notes published using 
the new system as well. The markup language used is ASCIIDoc[0], and the 
system that builds the site is Antora[1].

The site is built using the original "docs" repository[2]. The repo 
contains a set of configuration files and a build script (build.sh) that 
builds the whole site. If you have an issue to report that relates to 
the website itself - CSS problems, general look and feel, etc., this is 
the place to do so.

The Installation Guide content lives in docs-installation-guide[3]. Any 
issues relating to the actual Installation Guide (like, for example, how 
it talks about Red Hat Enterprise Virtualization even though it's been 
renamed to RHV) should be reported against this repo.

The third new repository, docs-web[4], contains the built site and 
shouldn't ever be touched. When I rebuild the site using the docs repo, 
I'll grab the output from docs/public, move it to docs-web/en-US, and 
tell Fabian to pull and publish that. Of course this will be automated 
eventually, and we should get a staging function as well using a 
different branch.

Next steps for me are to fix the navbars, make another repo that will 
store the UI project (that generates the UI bundle in docs-web which 
determines how the site looks), and I'll also write READMEs for each 
repo so you'll be able to see what each one is for without having to 
refer to this mail - this is just a quick explanation of how the system 
works.

Cheers,

Petr

[0] https://asciidoctor.org/docs/user-manual/
[1] https://antora.org/
[2] https://github.com/CentOS/docs
[3] https://github.com/CentOS/docs-installation-guide
[4] https://github.com/CentOS/docs-web