Astra Tutorials documentation

This repo contains the source files for the Astra Tutorials documentation.

The docs are written in AsciiDoc and use Antora to generate the output.

The Astra Tutorials docs are currently organized with one antora component, tutorials, and one module, ROOT. The ROOT module has directories for examples, partials, pages, attachments, and a nav.adoc for navigation.

Playbooks are YAML files used to build the website using antora. docs-src is the location of all content source, i.e., the AsciiDoc files.

The file structure has a particular form:

📒 repository 📄 antora.yml 📂 modules 📂 ROOT 📁 attachments 📁 examples 📁 images 📁 pages 📁 partials 📄 nav.adoc 📂 named-module 📁 pages 📄 nav.adoc 📁 packages

Note that our repository has one layer between repository and modules, a component. Each component must have a antora.yml file and a modules directory with a ROOT directory at a minimum.

Dependencies

Antora requires NodeJS, install it and then install the project dependencies:

npm install

Viewing the current HTML output

Generating and viewing the HTML output locally

The docs can be generated locally during development, to check work.

Use the build-locally.sh script with the appropriate docset to build:

./build-locally.sh tutorials

This build script will make sure you have the correct prerequisites installed for the antora build.

Publishing to the Tutorials website

Reporting bugs

File a GitHub issue.