Examples Directory and Files

Examples family directory

A module directory can contain a family directory named examples.

📂 modules
  📂 ROOT (1)
    📂 examples (2)
      📄 example-source-file.ext (3)
    📁 pages
    📄 nav.adoc
  📂 named-module (4)
    📂 examples (5)
      📄 example-source-file (6)
      📂 subdirectory-of-examples (7)
        📄 example-source-file.ext
    📁 images
1 A ROOT module directory.
2 An examples family directory. Antora classifies source files stored in an examples directory as examples.
3 An example source file.
4 A named module directory.
5 An examples family directory.
6 An example source file without a file extension. Antora will load example source files without extensions into the content catalog.
7 A subdirectory in examples. Source files stored in subdirectories of an examples directory are classified as examples.

The examples directory is optional. Antora applies preset behavior to the source files stored in an examples directory when it generates a site.

Example files

Antora classifies the source files stored in an examples directory as examples. Example files usually contain content such as source code samples, terminal output, data sets, etc.

When saving a new example file, keep the following filename requirements and recommendations in mind:

  • Spaces aren’t recommended in example filenames. While the AsciiDoc include directive does accept spaces in the target, some editing tools may not support it and is thus not recommended.

  • Uppercase letters and spaces aren’t recommended in example filenames. Some file systems aren’t case sensitive. Therefore, file conflicts could occur when using git depending on the file system a writer is using.

  • Save an example file with a valid file extension except when it’s common industry practice for that specific file type, such as Dockerfile, to not have an extension. Not using the correct file extension when saving an example file may limit your ability to apply some Antora extensions or upgrade to future capabilities.

An example file isn’t required to have a file extension. Unlike a publishable resource that’s treated as a hidden file if it’s missing a file extension, Antora will load an example that doesn’t have a file extension into its content catalog and assign the example a resource ID for referencing.

Antora doesn’t publish example files as individual site pages. An example must be referenced by an include directive from a page, or resource that’s eventually included in a page, for the example’s content to be published.

Except when it’s typical for a file type to not have a file extension, such as Dockerfile, it’s a good practice to save your example source files with their valid file extensions. Otherwise, you may not be able to use some Antora or Asciidoctor extensions that apply additional behavior to example files.
Examples shouldn’t be confused with the AsciiDoc example block, though an example file can be inserted into an example block using an include directive.

Learn more