Documentation Site Management

This page provides information about how the FoodTruckNerdz documentation site is built, managed, and deployed.

Architecture

The documentation site aggregates content from multiple component repositories into a single, unified documentation site using Antora. This allows each repository to maintain its own documentation while presenting it as a cohesive whole.

Site Specifics

This repository (docs) contains the core configuration for the documentation site:

  • Antora playbook files for building the documentation site

  • Configuration for aggregating documentation from component repositories

  • Custom UI overrides and supplemental files

  • Documentation about building and maintaining the documentation site itself

Building Locally

To build and preview the documentation site locally, see the Building Docs Locally guide.

The site can be built using either:

  • antora-playbook.yml - Standard playbook (uses GitHub URLs, suitable for CI/CD)

  • antora-playbook-local.yml - Local development playbook (uses local paths, faster builds)

CI/CD & Deployment

The documentation site is automatically built and deployed via GitHub Actions:

Having build issues? See Troubleshooting Antora Builds for common errors and solutions.

Site Structure

The generated documentation site is output to build/site/ and includes:

  • Unified navigation across all component repositories

  • Cross-references between components

  • Search functionality

  • Responsive design for all devices

Contributing to Documentation

When adding or updating documentation:

  1. Make changes in the appropriate component repository’s docs/ directory

  2. Build the site locally using antora-playbook-local.yml to preview changes

  3. Commit changes to the component repository

  4. Manually trigger a site redeploy (see Redeploying the Site) to see your changes online