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.

A private sister site (team.docs.foodtrucknerdz.com, repo FoodTruckNerdz/team-docs) holds member-only SOPs. Do not add those sources to this public playbook. GitHub’s free org plan cannot host Pages on private repos, so the sister site deploys to Cloudflare Pages.

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; rolling line releases/download/v2/ui-bundle.zip). 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 keeps a thin site/supplemental-ui/ overlay: the brand mark (img/foodtrucknerdz.svg) and a custom footer-content.hbs. Branding otherwise uses Valentus playbook site.keys (header_logo, site_home_url, header_doc_title, …) — do not fork Valentus partials/CSS unless you intend to override chrome. Track theme updates through the rolling v2 bundle URL (snapshot: true).

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