tonykay / rhtr-2020-collections-antora

Content container for AgnosticLP

Agnostic-Content generation

Definition

This component will allow generate a static website with your ASCII docs(adoc) files. It consist in 1 playbook which will use Antora to generate static html based on your doc repository.

Project structure:

• modules This is the directory used by Antora for reading the adocs and convert it into html.

  • ROOT This is where the navigation file should be (nav.doc)

    • pages This is were your adoc files should be. For more information about folder structure: https://docs.antora.org/antora/2.2/component-structure/

• build All the html files generated by the playbook, images and UI.

• antora-playbook.yml Ansible playbook will generate your website using Antora. It has your github repository. Antora only uses git repository it could be a local github repository or private/public repo. Antora needs a UI bundle because Antora separates documentation from UI. This repo is using a based image, but you can replace it with your own. https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable

• antora.yml is the antora component definition. It contains project definition, version, root page and file navigation path. Your component name and your version will be used for the file structure generation. So if you have component-A version 1.0 The build/site folder will have inside a component-A folder and a 1.0 folder on it too. More information: https://docs.antora.org/antora/2.2/playbook/private-repository-auth/

More information: https://docs.antora.org/antora/2.2/component-descriptor/ * nav.adoc is the navigation definition file for your website content(adoc). The format is based on : Ex. * Lab Overview For more information about navigation structure: https://docs.antora.org/antora/2.2/navigation/list-structures/

Steps to setup your environment

Pre-reqs:

• Ansible: 2.9.10 installed Installing Ansible with PIP $ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py $ python get-pip.py --user

More information: https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#from-pip

• Antora version: 2.2 installed Installing Antora using Node npm i -g @antora/[email protected] @antora/[email protected]

For more information: How to install Node: https://docs.antora.org/antora/2.2/install/macos-requirements/ How to install Antora: https://docs.antora.org/antora/2.2/install/install-antora/

Installation:

1. Download the source code from the repository git clone https://github.com/redhat-gpte-devopsautomation/agnosticlp-content.git

2. Goto your downloaded source folder: agnosticlp-content

3. Goto the antora playbook antora-playbook.com an update the source and branch with your repository. If you have a private repository best practices is to not hard code your credentials in the url, you can use a global variable or passing it in the command line. For more information:

4. Goto modules/ROOT/pages and place all your adoc there

5. Goto modules/ROOT/pages/images and place all your images there

6. Goto modules/ROOT/nav.adoc and modify the navigation according to your needs.

7. Run antora playbooks/antora-playbook.yml After the first time, if you done changes in your repo use: antora --fetch playbooks/antora-playbook.yml

Optional Feel free to update the antora component (antora.yml) if you need to change the page root or add more than one file navigation. By default the root page is index.html. You don’t need to specify it in the playbook unless you want to use a different page.

Remember all your built code will be placed on build/site. This is the folder you need to use to create your container image.