Examples Directory and Example Files

Examples family directory

A module directory can contain an optional family directory named examples.

šŸ“‚ modules
  šŸ“‚ a-named-module
    šŸ“‚ examples (1)
      šŸ“„ a-source-file.js (2)
  šŸ“‚ ROOT
    šŸ“‚ examples (3)
      šŸ“„ a-source-file.csv (4)
      šŸ“„ a-source-file.json
    šŸ“‚ pages
      šŸ“„ a-source-file.adoc
    šŸ“„ nav.adoc
1 An examples family directory in a named module directory
2 An example source file
3 An examples family directory in a ROOT module directory
4 An example source file

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

Examples

Examples are resources, such as source code (e.g., runner.js), terminal output, and data sets (e.g., choptank-co2.csv). The source files for examples are stored in an examples directory. Examples shouldn’t be confused with the AsciiDoc example block, though they can be inserted into an example block using an include directive.

If an example isn’t referenced in an AsciiDoc include directive, its content won’t be published to a site. Examples and tagged regions in an example can be inserted into any page or partial, regardless of the module or component version it belongs to, using the include directive and the example’s resource ID.

When referencing an example, the example$ family coordinate must be included in its resource ID. This coordinate is required because the include directive is also used to reference partials and, occasionally, pages.