Name Key

A component name is defined by assigning a value to the name key.

What’s a component name?

A component name, also called name, is the value assigned to the name key in a component version descriptor file (antora.yml). A component name typically represents the name of a project, library, service, etc., such as fauna, rudder, nrepl, etc. The value of a name key, in combination with the value of a version key, defines a component version.

How Antora uses name

The component name is fundamental to many of Antora’s operations. Antora uses the name:

as the component segment in page and asset URLs, unless the name of the component is ROOT.

Additionally, if the component title key isn’t set, Antora uses the name:

to sort component versions
for display purposes in the reference UI, which includes the component version page menu, component version selector menu, and the first breadcrumb position on a component version’s pages

Note that component name is case sensitive. This means that if you have two components with the same name that only are different in case, Antora will treat them as different components.

Content writers use the name as the component coordinate in resource IDs when referencing a resource in another documentation component.

name key

The name key is required. It’s set and assigned a value in a component version descriptor file (antora.yml).

Example 1. antora.yml with defined component name

name: colorado (1)

1	At the beginning of a new line, type `name`, directly followed by a colon and a space (`:` ). Then type the value you want assigned to `name`.

name requirements

The value assigned to the name key can contain letters, numbers, underscores (_), hyphens (-), and periods (.). To ensure portability between host platforms, letters used in the name value should be lowercase.

We strongly encourage you to select a name that only consists of lowercase characters. Component names, except for the special ROOT value, are used in your site’s URLs, therefore, using consistent casing makes the component name, and thus your site, more portable. That’s because some file systems, and thus the web server running on it, can’t distinguish between uppercase and lowercase characters.

The value cannot contain spaces, forward slashes (/), or HTML special characters (&, <, or >). The value cannot be empty.

See Customize the Title to learn how to display a name that contains spaces, uppercase letters, and other characters in your site’s UI.

ROOT component

When a component’s name is set to ROOT and its version is set to ~ in its antora.yml, then that component will be placed directly at the site’s root. It will not be placed inside a folder named ROOT. This is analogous to how modules named ROOT are placed at the root of their component.

Like other components, a ROOT component must have an antora.yml file and a modules folder. Let’s re-use the example from Module Segment in Page URLs:

📒 repository
  📄 antora.yml # name: ROOT and version: ~
  📂 modules
    📂 admin
      📂 pages
        📄 user-management.adoc
      📄 nav.adoc
    📂 ROOT
      📁 images
      📂 pages
        📄 deploy.adoc
        📄 index.adoc
      📄 nav.adoc

But now let’s instead assume that this component is named ROOT instead of hyperlemur, and its version set to ~. Here is what the URLs of the pages would be (assuming that html_extension_style is set to default in your playbook):

repository/modules/ROOT/pages/index.adoc: https://my-company.com/index.html (which means it will also be found at https://my-company.com)
repository/modules/ROOT/pages/deploy.adoc: https://my-company.com/deploy.html
repository/modules/admin/pages/user-management.adoc: https://my-company.com/admin/user-management.html

Because both the component name ROOT and the module name ROOT are excluded from URLs, the pages in the ROOT component’s ROOT module live directly at your site’s root, with root_component/modules/ROOT/pages/index.adoc serving as the site’s home page. That means that the index.adoc page in the ROOT module of the ROOT component acts as the site start page without having to specify it (no additional configuration is required).

If the ROOT component were to be versioned (i.e., have a non-empty version), then the files in that component version would be placed inside the version folder at the root of the site.

Because the ROOT component’s name does not appear in URLs, its modules are effectively scoped under your site’s root. This means it’s possible for pages in the ROOT component to conflict with pages in a named component. For instance, the file modules/xyz/pages/index.adoc in the (unversioned) ROOT component and the file modules/ROOT/pages/index.adoc in the (unversioned) xyz component will both resolve to the URL https://my-company.com/xyz/index.html, which is invalid. Therefore, you should be mindful of this situation when using modules in the ROOT component.

Since ROOT is not a user-friendly title for a component, you should also set the title in antora.yml, as demonstrated in Customize the Title.