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.

Reference: Antora Supplemental

For canonical Antora setup guidance (Root vs. Subfolder strategy, GitHub Pages, private repos), see antora-supplemental.github.io/docs. A comparison of FTN’s current setup with that reference is at Antora Supplemental Comparison.

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

UI bundle

The published site uses antora-supplemental/valentus-theme as the base Antora UI bundle (ui.bundle.url in the playbook; use the rolling line releases/download/v1/ui-bundle.zip asset). The bundle includes doc-site chrome and bundled dark mode (successor to the retired antora-dark-theme package). Theme static assets (including the default img/logo.svg placeholder and VCS icons under img/vcs/) ship in that bundle. FoodTruckNerdz layers custom partials, CSS, and scripts on top via site/supplemental-ui/; site-specific images live there too (for example img/foodtrucknerdz.svg for the header). Do not duplicate bundle img/ assets in supplemental unless you intend to override them. Track theme updates through the release bundle URL only. The dark-mode script in site/supplemental-ui/js/site-dark-mode.js is maintained in this repository in lockstep with valentus-theme 1.1+ / antora-dark-mode (system / override behavior); port upstream JS changes from theme release notes when you adopt a new bundle version.

Optional site.keys in the playbook control the footer label and link for the base theme (keep them aligned with the bundle you reference in ui.bundle):

  • ui_bundle_name — display name (exposed as uiBundleName in the UI)

  • ui_bundle_url — project URL (exposed as uiBundleUrl)

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