This section describes how to build documentation locally. We recommend that you do this to test major documentation changes, particularly if adding a lot of new content to the documentation or making significant revisions to existing documentation.
Antora is a documentation site generator based around the AsciiDoc format. To install Antora, follow the instructions on the Antora website.
If you already know how to use git, then this is going to sound very familiar. If not, here’s the full walk-through:
If the project that you are working in already has version branches, then you will want to set up local copies of those as well.
After you have cloned the repo to your local system, you can track those branches with the command:
git checkout -b <local_branch_name> <remote_repo>/<remote_branch_name>
The documentation for the project lives in the
docs directory within the source code repository you have checked out.
Each main section is structured in directories that contain the text
Write the text files in the AsciiDoc format.
You need to include every new directory or text file in the general structure of the documentation.
nav.adoc file defines the content hierarchy.
.About (1) * xref:about:welcome.adoc[Welcome] (2) * xref:about:legal-notice.adoc[Legal Notice] (2) .Installation (3) * xref:installation:requirements.adoc[Requirements] (4) * xref:installation:rpm.adoc[Installing on RPM-based Linux (CentOS, Fedora, OpenSuse, RedHat)] (4) * xref:installation:debian.adoc[Installing on Debian/Ubuntu] (4)
|1||Friendly directory name About that appears in the left navigation.|
|2||Each topic in the About section, written as a cross reference to the directory, file name, and friendly name that appears in the left navigation.|
|3||Second section, Installation.|
|4||Each topic in the Installation section.|
For information on directory structure for images files, see Include images.
The documentation is located in the
Transforming an Antora repo into a documentation site is pretty easy: