Pages Directory and Files

Pages family directory

A module directory can contain a family directory named pages. The pages directory can contain subdirectories. Only AsciiDoc source files with the file extension .adoc should be stored in the pages directory and its subdirectories because Antora applies preset behavior to page files when it runs.

📂 modules
  📂 named-module (1)
    📂 pages (2)
      📄 page-source-file.adoc (3)
      📂 subdirectory-of-pages (4)
        📄 page-source-file.adoc
  📂 ROOT (5)
    📂 pages (6)
      📄 page-source-file.adoc
    📄 nav.adoc

1	A named module directory.
2	A pages family directory. Source files stored in pages are classified as pages.
3	A page file marked up with the AsciiDoc syntax and saved with the valid .adoc file extension.
4	A subdirectory in pages. Source files stored in subdirectories of a pages directory are classified as pages.
5	A ROOT module directory.
6	A pages family directory.

The pages directory is optional. That is, if a module doesn’t have any page files, don’t create a pages directory in the module. If you set up a pages directory, the pages directory or a subdirectory of pages must contain at least one AsciiDoc source file.

Page files

Antora classifies the source files stored in a pages directory as pages. Pages are structured as individual documents with a title, marked up using the AsciiDoc syntax, and saved with the .adoc file extension. Using a page’s resource ID, you can cross reference a page from other pages, resources, or navigation files in your site or include a page into other pages or resources in your site.

A page file is a publishable resource unless it’s marked as hidden or unpublished. That means Antora automatically converts each page to HTML and publishes it as an individual page in a site, even if the page isn’t referenced by another resource or navigation file. Antora uses the pages-relative directory path (if present), filename of the page, and specified HTML extension style when building the URL of a page.