Getting Started

How to start:

podman run --rm --name antora -v $PWD:/antora:z -p 8080:8080 -i -t quay.io/rbohne/antora-viewer:latest

1. Create a git repo from this template

2. Clone the repo and cd into it

3. Run ./utilities/lab-serve

4. Open http://localhost:8080 in your browser

5. Run ./utilities/lab-build to build your html

Your lab should now update and on day 1 will look more or less like this:

Now you are ready to go! You can start editing the files in the content/modules/ROOT/pages/ directory.

Today you have to run ./utilites/build to rebuild your html but very shortly we will be adding live updating. I.E. on every save the lab will re-build in real time. In addition, many modern editors such as Visual Studio Code offer live Asciidoc Preview extensions.

Understanding the Basic Template Directory Structure

./content/modules/ROOT/
├── assets
│   └── images                       # Images used in your content
│       └── example-image.png
├── examples                         # You can add downloadable assets here
│   └── example-bash-script.sh       # e.g. an example bash script
├── nav.adoc                         # Navigation for your lab
├── pages                            # Your content goes here
│   ├── index.adoc                   # First page of your lab, e.g. overview etc
│   ├── module-02.adoc
│   └── module-03.adoc               # Sample lab has 3 modules including index.adoc
└── partials                         # You can add partials here, reusable content inserted inline into your modules
    └── example_partial.adoc

Development Cycle

1. Edit your content in content/modules/ROOT/pages/

2. Run ./utilities/build to build your html

3. Use git to branch and commit your work

4. Push your work to your repo

   1. You should use git tags or git branches in production

   2. However development items default to the head of main

Configuring your Lab

Project Zero Lab repos have 3 yaml files that control the build and deployment of your lab. However typically you will only need to only make very few edits

├── content
│   └── antora.yml                  # You can add "inline vars" here to render within your content
├── zero-touch-config.yml            #
└── zero-touch-site.yml