Component Documentation Navigation Guide

Overview

The auto build script, generate-components.nav.js, automatically generates Antora navigation for upstream component documentation by scanning their docs/ and guides/ directories and creating a structured navigation file.

How It Works

Scans each component directory in trento-docs-site/build/tmp_components/
Extracts titles from AsciiDoc files using = Title headers
Generates hierarchical navigation with proper indentation
Outputs nav_components.adoc for inclusion in Antora site

All content changes should happen in the upstream repositories (e.g., trento-project/agent, trento-project/web, etc.). The script reflects those changes into the Antora site during the CI build.

Process Flow

The CI pipeline clones all upstream repos into trento-docs-site/build/tmp_components/.
The script (trento-docs-site/scripts/generate-components.nav.js):
1. Creates the output directory trento-docs-site/build/gen_navigation if it doesn’t exist.
2. Reads the list of component directories from trento-docs-site/build/tmp_components/.
3. For each component:
  1. Checks for a root README.adoc file (components without README are skipped).
  2. Extracts the title from README using regex /^=\s*(.+)/m.
  3. Adds the README to navigation as a level 3 entry (***).
  4. Scans docs/ and guides/ directories for .adoc files.
  5. Ignores directories named image, images, and examples.
  6. For each .adoc file found:
    
    Extracts title from first-level AsciiDoc header or uses filename as fallback.
    
    Creates xref links with format xref:ROOT:componentName:filePath[title].
    
    Handles nested directories by creating appropriate navigation levels.
  7. Skips any README files found inside docs/ or guides/ directories.
4. Builds the final navigation content starting with ** Components header.
Writes the generated navigation to trento-docs-site/build/gen_navigation/nav_components.adoc.
Prints a comprehensive summary log showing:
1. Number of processed components with their names.
2. Complete generated navigation content.
3. Output file path confirmation.

Required Structure

Component Root Structure

Each upstream component, like trento-project/agent, trento-project/web must have this structure:

component/
├── README.adoc        # In navigation (*** level)
├── CONTRIBUTING.adoc  # Optional, accessible, not in navigation, but a redirect from README to Contributing works
├── docs/              # (Optional not in navigation)
│   └── guide.adoc     # In navigation (**** level)
└── guides/            # (Optional not in navigation)
    └── tutorial.adoc  # In navigation (**** level)

Documentation Directory Structure

Inside docs/ and guides/ directories:

docs/
├── installation.adoc        # Direct files → navigation level ****
├── configuration.adoc       # Direct files → navigation level ****
├── Api/                     # Subdirectory → navigation level ****
│   ├── README.adoc          # Creates clickable directory entry: "Api" → Api/README.adoc
│   ├── authentication.adoc  # Nested files → navigation level *****
│   ├── endpoints.adoc       # Nested files → navigation level *****
│   ├── images/              # IGNORED - excluded from navigation
│   └── examples/            # IGNORED - excluded from navigation
├── Development/             # Subdirectory → navigation level ****
│   ├── setup.adoc           # Nested files → navigation level *****
│   ├── Testing/             # Deeper nesting → navigation level ***** TOO DEEP - Try to avoid
│   │   ├── unit-tests.adoc  # Files inside → navigation level ****** TOO DEEP - Try to avoid

Directory README Behavior

When a directory contains a README.adoc file:

Navigation label: Uses the directory name (not the README title)
Link target: Points to the README file inside that directory
Purpose: README provides context/overview for the directory contents

Example:

docs/
└── Api/             # Directory name: "Api"
    └── README.adoc  # Title: "= Title Comprehensive API Documentation Guide"

Generated navigation:

**** xref:ROOT:component:Api/README.adoc[Api]    # Label = "Api" (directory name)

Not:

**** xref:ROOT:component:Api/README.adoc[Comprehensive API Documentation Guide]

This keeps navigation labels concise and consistent while allowing README content to provide detailed context.

Important: This behavior is different from component root READMEs, which do use their extracted title:

Component root README: Uses = Title from README content
Directory README: Uses directory name (ignores README title)

Best Practice: For directory READMEs, consider making the directory name descriptive since it becomes the navigation label.

Generated Navigation Output

Real-World Example: MCP Server

mcp-server/
├── README.adoc                            # = Title Trento MCP Server
├── docs/
│   ├── Developer/                         # Directory → nav label: "Developer"
│   │   ├── README.adoc                    # README title ignored for nav label
│   │   └── getting-started.adoc           # = Title Getting Started
│   ├── examples/                          # IGNORED - entire directory excluded
│   │   └── ...                            # All contents IGNORED
│   └── Trento MCP Server documentation/   # Directory → nav label: "Trento MCP Server documentation"
│       ├── README.adoc                    # README title ignored for nav label
│       ├── configuration-options.adoc     # = Title Configuration Options
│       ├── integration-suse-ai.adoc       # = Title SUSE AI Integration
│       └── integration-vscode.adoc        # = Title VS Code Integration

Generated Navigation

** Components

*** xref:ROOT:mcp-server:README.adoc[Trento MCP Server] # Component README (level ***)
**** xref:ROOT:mcp-server:Developer/README.adoc[Developer] # Directory with README (level ****)
***** xref:ROOT:mcp-server:Developer/getting-started.adoc[Getting Started] # Nested files (level *****)
**** xref:ROOT:mcp-server:Trento MCP Server documentation/README.adoc[Trento MCP Server documentation] # Directory with README (level ****)
***** xref:ROOT:mcp-server:Trento MCP Server documentation/configuration-options.adoc[Configuration Options] # Nested files (level *****)
***** xref:ROOT:mcp-server:Trento MCP Server documentation/integration-suse-ai.adoc[SUSE AI Integration] # Nested files (level *****)
***** xref:ROOT:mcp-server:Trento MCP Server documentation/integration-vscode.adoc[VS Code Integration] # Nested files (level *****)

Content Guidelines

AsciiDoc File Requirements

✅ Correct Title Format

= SUSE AI Integration       ← This becomes the navigation label

== Prerequisites           ← Section headers are ignored for navigation

❌ Incorrect Format

== SUSE AI Integration     ← Won't be extracted as wrong level
SUSE AI Integration        ← Plain text won't be extracted

Directory Naming Conventions

Use descriptive names: Developer/ not Dev/
Consider spaces as folder names become navigation labels: Trento MCP Server documentation/ not Trento_MCP_Server_documentation/

Structure Best Practices

RECOMMENDED Structure

component/
├── README.adoc                   # Component overview
├── docs/
│   ├── installation.adoc         # Getting started
│   ├── configuration.adoc        # Basic setup
│   └── Extras/                   # Grouped advanced topics
│       ├── custom-setup.adoc
│       └── troubleshooting.adoc
└── guides/
    ├── quickstart.adoc           # Tutorial content
    └── examples.adoc

AVOID Deep Nesting

component/
└── docs/
    └── setup/
        └── installation/
            └── guide.adoc    # TOO DEEP! Creates unusable navigation

BETTER Alternative

component/
└── docs/
    ├── guide.adoc
    ├── Installation/
    │   ├── README.adoc                # Installation overview
    │   ├── linux.adoc                 # Platform-specific guides
    ├── images/                        # Excluded from navigation but all images in the articles should be here
    │   ├── installation-diagram.png   # Image assets for documentation
    │   └── configuration-example.png
    ├── configuration.adoc             # Other documentation
    └── troubleshooting.adoc

File Processing Rules

Processed Files

Format: *.adoc files only
Title extraction: Uses = Title header format
Fallback: Filename (without extension) if no title found
Encoding: UTF-8 (configurable)

Ignored Content

Directories: image, images, and examples are automatically excluded
Files: Non-.adoc files are ignored
README files: Inside docs/ and guides/ are skipped (handled at directory level)

Cross-platform compatibility (GitHub + Antora)

To ensure documentation works seamlessly on both GitHub and Antora, follow these conditional formatting patterns:

File path prefixes

In root README files, use conditional prefixes to ensure proper navigation:

ifndef::site-gen-antora[:relfileprefix: docs/]
ifndef::site-gen-antora[:relfileprefix: guides/]

Example: Trento Agent example

This ensures links work correctly in both GitHub (which needs the path prefix) and Antora (which doesn’t).

Image handling

For images, use the conditional imagesdir attribute:

ifndef::imagesdir[:imagesdir: ../images]

Store all images in the docs/ and guides/ images directory of your component.

Images can be embedded in an article with the set imagesdir :

image::trento-spa-refresh.png[Refresh token success diagram]

.Refresh token failure diagram
image::trento-spa-refresh-failed.png[Refresh token failure diagram]

The Antora collector automatically scans image directories and places them correctly:

- dir: trento-docs-site/build/tmp_components/web/guides/images
  files: '**/*.{png,jpg,jpeg,svg,gif}'
  into: modules/web/images/

Cross-references (Root README only)

When linking from the root README to other files in the same component root, use conditional syntax:

ifdef::site-gen-antora[]
See xref:CONTRIBUTING.adoc[contribution guidelines].
endif::[]
ifndef::site-gen-antora[]
See link:CONTRIBUTING.adoc[contribution guidelines].
endif::[]

This ensures proper xref resolution in Antora while maintaining GitHub compatibility. This pattern is only needed in root README files when linking to other root-level files.

Configuration Options

The script supports various configuration options in CONFIG:

const CONFIG = {
  docsDirNames: ["docs", "guides"],             // Directories to scan
  ignoredDirs: ["image", "images", "examples"], // Directories to ignore
  readmeFileName: "README.adoc",                // README file name
  docsFileFormat: ".adoc",                      // File format to process
  readmeLevel: "***",                           // Navigation level for READMEs
  docsLevel: "****",                            // Navigation level for docs files
  xrefModule: "ROOT",                           // Antora module for cross-references
  lineEnding: "\n"                              // Line ending format
};

How to add new developer documentation?

Content Creation Checklist

README.adoc exists in component root
AsciiDoc files use = Title format
Directory structure is logical and shallow
File names are descriptive and kebab-case
No content in ignored directories

Summary

If you contribute documentation to any Trento upstream repository:

Always add or update the README.adoc at the root for that component.
Place .adoc documentation in docs/ and guides/.
Do not put .adoc files inside image, images, and examples folders (they are ignored).
Use proper first-level titles in .adoc files (= Title My Title).
Follow cross-platform compatibility patterns:
- Use ifndef::site-gen-antora[:relfileprefix: docs/] or guides/ in root README files.
- Use ifndef::imagesdir[:imagesdir: ../images] for image directories.
- Store images in docs/images/ or guides/images/ directories.
- Use conditional xref/link syntax in root README when linking to root-level files.
Structure for usability:
- Keep directory nesting shallow
- Use descriptive folder and file names
- Group related content logically
- Think about end-user navigation experience
Remember: The script runs automatically during CI — the nav file is never edited manually.