component descriptor

Component Descriptor (antora.yml)

Table of Contents

• Introduction
• Our Component Descriptor (antora.yml)
• name
• title
• version
• start_page
• nav

Introduction

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

• antora.yml

It is also known as the component descriptor.

Our Component Descriptor (antora.yml)

# 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

❗

Building for a Product You cannot have both uyuni keys and suma keys set at the same time. You must comment out one or the other. This replacement should happen automatically when building via our Makefile however I have seen it comment out both keys and then fail a build. "FIX ME, check with Karl on SED replacement!" If this occurs check the antora.yml file. Comment out the product you do not want to build for and uncomment the desired keys for your target output.

name

This value will always be either suse-manager or uyuni. Notice letter case, its easy to get these mixed up and wonder why your site will not build.

title

This value will always be either SUSE Manager or Uyuni.

It affects the following UI components:

• 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 default for our purposes should always be master

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.

You must pick only one of these keys when building. Comment out the other depending on your target.

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.