Antora Site Configuration Guide

1. Overview

This guide covers site-level Antora configuration for documentation sites. It addresses the configuration files and customizations that apply across the entire site, as opposed to individual component or module configuration.

For component and module configuration, see the Antora Configuration Guide. This guide focuses on site-wide configuration including:

  • Antora playbook configuration

  • Navbar and header customization

  • Search integration

  • Supplemental UI files

2. Antora Playbook Configuration

The antora-playbook.yml file defines the site-wide configuration including content sources, UI bundle, and extensions.

2.1. Key Sections

site:
  title: Site Title
  url: https://docs.example.com/
  start_page: component::index.adoc

antora:
  extensions:
    - require: '@antora/lunr-extension'

content:
  sources:
    - url: ./
      branches: HEAD
      start_path: docs
    - url: https://github.com/org/other-docs.git
      branches: main
      start_path: docs

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
  supplemental_files: ./supplemental

3. Supplemental Files

Supplemental files allow customization of the Antora UI without creating a custom UI bundle. They are placed in a directory referenced by ui.supplemental_files in the playbook.

3.1. Directory Structure

supplemental/
├── partials/
│   ├── header-content.hbs    # Custom navbar/header
│   ├── head-styles.hbs       # Custom CSS styles
│   └── footer-content.hbs    # Custom footer (optional)
└── ui.yml                    # UI configuration (optional)

3.2. Common Customizations

3.2.1. Custom Header (header-content.hbs)

The header-content.hbs partial overrides the default Antora header. Common customizations include:

  • Site title as home link

  • Navigation dropdown menus

  • Search input placement

3.2.2. Custom Styles (head-styles.hbs)

The head-styles.hbs partial adds custom CSS to the site. Always include the default stylesheet first:

<link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">
<style>
/* Custom styles here */
</style>

4. Navbar Configuration

The navbar provides site-wide navigation to documentation components. It should be kept in sync with the content sources defined in the playbook.

4.1. Navbar Structure

<header class="header">
  <nav class="navbar">
    <div class="navbar-brand">
      <a class="navbar-item" href="{{{or site.url (or siteRootUrl siteRootPath)}}}">
        <span class="site-title">{{{site.title}}}</span>
      </a>
    </div>
    <div class="navbar-menu">
      <div class="navbar-start">
        <!-- Documentation dropdown -->
      </div>
      <div class="navbar-end">
        <!-- Search input -->
      </div>
    </div>
  </nav>
</header>

4.2. Documentation Dropdown Menu

The navbar dropdown should link to Antora components using site-relative URLs:

<div class="navbar-item has-dropdown is-hoverable">
  <a class="navbar-link">Documentation</a>
  <div class="navbar-dropdown">
    <a class="navbar-item" href="{{{siteRootPath}}}/component-name/">
      Component Title
    </a>
  </div>
</div>

Synchronization Requirement: The navbar dropdown menu must stay synchronized with:

  1. antora-playbook.yml - Content sources define which components are available

  2. docs/modules/ROOT/nav.adoc - The ROOT module navigation links to components

When adding or removing Antora components, all three locations must be updated together.

5. Component Synchronization

When adding or removing Antora components from a documentation site, three files must be updated together:

File Purpose Format

antora-playbook.yml

Defines content sources

YAML content source entry

docs/modules/ROOT/nav.adoc

Left navigation menu

Antora xref syntax

supplemental/partials/header-content.hbs

Navbar dropdown menu

Site-relative URLs

5.1. Synchronization Formats

antora-playbook.yml (content source):

content:
  sources:
    - url: https://github.com/org/component-docs.git
      branches: main
      start_path: docs

nav.adoc (Antora xref syntax):

* Documentation Components
** xref:component-name::index.adoc[Component Title]

header-content.hbs (site-relative URL):

<a class="navbar-item" href="{{{siteRootPath}}}/component-name/">
  Component Title
</a>

5.2. Adding a New Component

  1. Add the content source to antora-playbook.yml

  2. Add the xref to docs/modules/ROOT/nav.adoc

  3. Add the navbar link to supplemental/partials/header-content.hbs

  4. Rebuild the site to verify

5.3. Removing a Component

  1. Remove the content source from antora-playbook.yml

  2. Remove the xref from docs/modules/ROOT/nav.adoc

  3. Remove the navbar link from supplemental/partials/header-content.hbs

  4. Rebuild the site to verify

6. Search Configuration

Antora supports client-side search using the official Lunr extension.

6.1. Enabling Search

Add the extension to antora-playbook.yml:

antora:
  extensions:
    - require: '@antora/lunr-extension'
      index_latest_only: true

Add the dependency to package.json:

{
  "devDependencies": {
    "@antora/lunr-extension": "^1.0.0-alpha.8"
  }
}

6.2. Search Input Placement

Place the search input in header-content.hbs:

<div class="navbar-item search hide-for-print">
  <div id="search-field" class="field">
    <input id="search-input" type="text" placeholder="Search the docs">
  </div>
</div>

6.3. Search Results Styling

Custom CSS for search results goes in head-styles.hbs. Key classes:

  • .search-result-dropdown-menu - Results container

  • .search-result-dataset - Results list

  • .search-result-item - Individual result

  • .search-result-document-title - Page title column

  • .search-result-document-hit - Content excerpt column

  • .search-result-highlight - Highlighted search terms

7. Handlebars Variables

Common Handlebars variables available in supplemental partials:

Variable Description

{{{site.title}}}

Site title from playbook

{{{site.url}}}

Site URL from playbook

{{{siteRootPath}}}

Relative path to site root

{{{uiRootPath}}}

Relative path to UI assets

{{{page.url}}}

Current page URL

{{{page.title}}}

Current page title

8. Quality Checklist

Before deploying site configuration changes:

Playbook Configuration:

  • All content sources defined and accessible

  • Site URL correctly configured

  • Extensions properly configured

  • Supplemental files path correct

Navbar Configuration:

  • Site title links to home page

  • Dropdown menu matches content sources

  • All component links use correct URLs

  • Mobile menu works correctly

Component Synchronization:

  • Navbar dropdown matches nav.adoc entries

  • All three files updated together when components change

  • No dead links to removed components

Search Configuration:

  • Search input appears in navbar

  • Search results display correctly

  • Search index generated during build

9. Common Pitfalls

9.1. Navbar Links Out of Sync

Problem: Navbar dropdown has different components than nav.adoc or playbook.

Solution: Always update all three files together when adding/removing components. See Component Synchronization.

9.2. Search Not Working

Problem: Search input appears but doesn’t return results.

Solutions:

  • Verify @antora/lunr-extension is in dependencies

  • Check extension is configured in playbook

  • Ensure npm install was run

  • Check browser console for JavaScript errors

9.3. Custom Styles Not Applied

Problem: CSS changes in head-styles.hbs not visible.

Solutions:

  • Ensure default stylesheet is included first

  • Clear browser cache

  • Verify supplemental_files path in playbook

9.4. Broken Component Links

Problem: Navbar links to components return 404.

Solutions:

  • Verify component name matches directory in build output

  • Use {{{siteRootPath}}} prefix for site-relative URLs

  • Check component is defined in playbook content sources

10. Additional Resources

This guide ensures consistent site-wide Antora configuration across documentation projects.