Antora Documentation Site UI

This directory contains the customized UI bundle for the Trento documentation site, based on the Antora default UI. The Antora site assembly in trento-docs-site/ consumes the generated UI bundle from this directory. Refer to the full upstream documentation at Antora Default UI Documentation.

Project Structure

src/            # UI source files (layouts, partials, helpers)
gulp.d/         # Gulp task implementations and task helpers
preview-src/    # Demo content for local preview
public/         # Output directory for preview site
build/          # Build artifacts including ui-bundle.zip
gulpfile.js     # Gulp tasks for building the UI

Install dependencies

npm install

Supported build tasks

npx gulp --tasks-simple

You should see:

default          // Runs the default task, which maps to the publishable bundle flow
clean            // Removes generated files and directories (e.g., build/, public/)
lint             // Lints JavaScript and stylesheet source files
format           // Applies formatting to source files using configured linters
build            // Stages the UI assets used for bundling
bundle           // Cleans, lints, builds, and creates the publishable UI bundle
bundle:pack      // Creates a zip archive of the UI bundle as 'ui-bundle.zip' in the build/ folder
preview          // Starts a local preview server using content in preview-src/
preview:build    // Builds a static site for preview into the 'public/' directory

Develop and Preview Changes

To continuously build and preview your UI as you make changes, run:

npx gulp preview

This starts a local development server using the content in preview-src/, allowing you to see updates live in the browser on port 5252.

Use npx gulp preview when you are working only on the UI and want fast feedback on templates, styles, or helpers. This preview does not rebuild the docs hub automatically.

Build the UI Bundle

When you’re ready to package the UI for use in the actual documentation site, run:

npx gulp bundle

This command runs the full publishable UI flow and creates build/ui-bundle.zip.

The Antora site in trento-docs-site/ uses this bundle from trento-docs-site-ui/build/ui-bundle.zip in the playbook configuration.

If you change the UI sources, you must rebuild the UI bundle and commit the updated build/ui-bundle.zip.

Otherwise the previously generated bundle will still be used, and your UI changes will not be applied in the site build.

If you preview the docs hub with docker compose or by running npx antora, the build consumes the checked-in UI bundle. Raw UI source changes are not visible there until ui-bundle.zip is rebuilt.

Customize the UI

To learn how to customize templates, partials, helpers, and other UI components, refer to the official Antora UI customization guide:

https://docs.antora.org/antora-ui-default/templates/