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/antora-dark-theme as the base Antora UI bundle (ui.bundle.url in the playbook; use the releases/latest/download/ui-bundle.zip asset). FoodTruckNerdz layers custom partials, CSS, and scripts on top via site/supplemental-ui/. The package.json prebuild step runs site/scripts/sync-antora-dark-theme.cjs, which copies only img/ from the antora-dark-theme npm package into that folder (supplemental site-extra.css and other CSS stay repo-maintained so CI does not overwrite FoodTruckNerdz-specific rules). The dark-mode script in site/supplemental-ui/js/site-dark-mode.js is maintained in this repository in lockstep with antora-dark-theme 1.0+ (system / override behavior); bump the antora-dark-theme devDependency after a new theme release (push a v* tag on the theme repo; CI builds the release and can publish the npm package), then pnpm install.

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