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:
-
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 you have two components with the same name that only 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).
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 encouraged 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.