On this page, you’ll learn:
The difference between a standard and a partial page.
How Antora handles an index.adoc file stored in the ROOT module of a component.
Antora generates site pages from AsciiDoc files.
AsciiDoc files are text files marked up with the AsciiDoc syntax and saved with the file extension
Whether Antora automatically processes an AsciiDoc file depends on where it is stored in a documentation component.
Antora generates one site page for each AsciiDoc file located in the pages directory of a module. These files are converted to individual HTML pages automatically. Another way to think about this: one AsciiDoc file in equals one HTML page out.
my-page.adoc ⇒ my-page.html
While all standard pages are automatically included in your site, if you want visitors to locate and go to a specific page using a component navigation menu, then you must add a cross reference (
xref) to that page in the appropriate navigation source file.
If you don’t want to include a page in a component menu, visitors will still be able to find it using search tools and through links to it on other pages, and in some scenarios, through dropdown menus such as the page version selector.
Partials are AsciiDoc files located in a partials directory. These files are not converted to HTML by Antora automatically. Instead, they must be referenced by an include directive in a standard page.
Partials are good for storing snippets of content, such as concept definitions or project introductions, that you reuse in one or more standard pages. When you change the content in a partial, those changes will be disseminated to all of the standard pages where you embedded that partial with an include directive.
If a file named index.adoc exists in the ROOT module of a component, Antora will automatically set this page as the start page of that component.
component:ROOT:index.adoc ⇒ site.com/component/index.html