Examples

Reusable, single source examples

Examples are useful for storing source code, queries, configuration parameters, terminal output, logs, data sets, and other non-AsciiDoc files, that you reuse in one or more pages throughout your site. Changes you make to an example file will disseminate to all of the pages where you referenced the example the next time you build your site.

Example filenames and file extensions

Example files are usually non-AsciiDoc files. They’re stored in an examples directory.

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.

Unlike publishable resources, an example file without a file extension isn’t treated as a hidden file. 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.

Example file usage

Typically, content from an example file is inserted into source, listing, and literal blocks. Regardless of the component version an example file belongs to, it can be referenced by any page or partial in your site. An example is referenced using its resource ID and the AsciiDoc include directive. You can even select regions or lines from an example, instead of all of the example’s content, and insert only those regions or lines using the include directive’s tag, tags, or lines attributes.

Examples shouldn’t be confused with the AsciiDoc example block, though content from an example file can be inserted into an example block using an include directive.