Recommendations for Module Directory Names
When you’re creating module directories, you need to consider how your team will use the files stored in them and how their names will affect your site’s URLs.
Selecting module folder names
Antora assigns the name of a module from the name of a module folder. A module name is used in page IDs and the resource IDs of images, examples, and partials. It’s also used in the URLs of the pages assigned to that module (except for the ROOT module).
When choosing a module folder name, keep the following requirements and recommendations in mind:
-
Named module directories can’t contain blank spaces or forward slashes (
/). These characters aren’t permitted in the targets of AsciiDoc cross references, image macros, or include directives. -
If possible, don’t use uppercase letters, underscores (
_), and other characters that aren’t recommended in URLs. Such characters can limit web server portability, downgrade site search results, and cause visitor accessibility problems. -
If your team often references pages, examples, images, or partials across modules, they’ll have to type a module’s name in page and resource IDs, so don’t make the folder name, and hence the module name, too long or hard to remember. Good module names are short and descriptive.
Example 1 shows a set of standard directories with three named module directories.
📒 repository
📂 docs
📄 antora.yml
📂 modules
📂 gear (1)
📂 images
📄 a-source-file.jpg
📂 la-garita (2)
📂 pages
📄 a-source-file.adoc
📂 ROOT (3)
📂 pages
📄 a-source-file.adoc
📄 nav.adoc
📂 sdk (4)
📂 examples
📄 a-source-file.js
📂 pages
📄 a-source-file.adoc
📄 nav.adoc
| 1 | Module directory named gear |
| 2 | Module directory named la-garita |
| 3 | ROOT module directory |
| 4 | Module directory named sdk |
Antora would calculate the following module names from the named module directories in Example 1: gear, la-garita, and sdk.