component descriptor

Component Descriptor (antora.yml)

Table of Contents

• name
• title
• version
• start_page
• nav

When Antora builds a static site from one of our playbooks it uses an additional file to specify the location of all documentation sources(modules), which page it should start on etc. This file is called:

• antora.yml

It is also known as the component descriptor.

antora.yml (For SUSE Manager and Uyuni)

# Uncomment name and title to build for SUMA
name: suse-manager (1)
title: SUSE Manager (2)

# Uncomment name and title to build for Uyuni
#name: uyuni
#title: Uyuni

# Default should always be MASTER Otherwise the branch will be added to the URL slug
version: master (3)

# Uncomment one of the following home pages depending on your target (SUMA or Uyuni)
start_page: ROOT:index-suma (4)
#start_page: ROOT:index-uyuni

nav: (5)
  # ROOT Modules (release notes, license, index pages and resource links)
  - modules/ROOT/nav.adoc

  # Installation Guide
  - modules/installation/nav-installation-guide.adoc

  # Client Configuration Guide
  - modules/client-configuration/nav-client-config-guide.adoc

  # Upgrade Guide
  - modules/upgrade/nav-upgrade-guide.adoc

  # Reference Manual
  - modules/reference/nav-reference-manual.adoc

  # Administration Guide
  - modules/administration/nav-administration-guide.adoc

  # Salt Guide
  - modules/salt/nav-salt-guide.adoc

  # Retail Books
  - modules/retail/nav-retail.adoc

  # Architecture
  #- modules/architecture/nav-architecture-components-guide.adoc

1. Name Key

2. Title Key

3. Version Key

4. Start Page Key

5. Nav Key

name

The value of the name key is the component name that is used when the component is referenced in a cross reference. The value can contain letter, number, underscore (_), hyphen (-), and period (.) characters. The component name does not have to be the same as the name of the repository it lives in.

title

The value of the title key is the display name for the component. It’s used anywhere in the UI that the component is identified. This includes:

• component navigation menu

• component version selector

• first breadcrumb position

The component title does not have to be the same as the component name.

version

The value of the version key is both the display name and version coordinate. This includes:

• page ID and cross references (version@)

• component navigation menu

• component version selector

• page version selector

• edit page URI (not visible)

The value can contain letter, number, period (.), underscore (_), and hyphen (-) characters. If the value starts with a number, it must be contained within a set of single quote marks (').

Example version key values

• '1.0'

• v2.0-beta

• latest

The version key value isn’t related to a repository branch name or tag in any way. Instead, the value should be useable by the documentation writers and useful to the readers.

start_page

Our start page looks for a file named index-suma.adoc or index-uyuni.adoc in the ROOT module to use as the start page.

Start page value examples

start_page: ROOT:index-suma

# or

start_page: ROOT:index-uyuni

nav

The nav key accepts a list of navigation files. Each value specifies the path to a navigation file (e.g., modules/module-name/nav.adoc).

The order of the values listed in the nav key dictates the order the contents of the navigation files are assembled in the published component menu (left navigation bar).

ℹ️	Disabling Books It is possible to disable books from publishing by commenting out the nav that leads to any book module in question. For example: nav: # Retail Books - modules/retail/nav-retail.adoc # Architecture #- modules/architecture/nav-architecture-components-guide.adoc

For more information see the official Antora documentation on the Component descriptor.