modifié le

Navigation

Intra component navigation

Navigation management is manual, It is carried out at the level of each component, via an .adoc file containing a multi-level list. The levels of the items in the list correspond to the levels of the items in the menu. If the element is a link, we obtain a clickable element in the menu. If the element is just text, then we just get a label in the menu.

The navigation can be entirely in a single .doc file of the component, or be broken down by module, and aggregated at the component level. The links are not links to generated HTML pages, but links to the source .adoc files, in the form:

xref:component:page.adoc[optionnal label]

If the label is omitted, the top-level title of the pointed document replaces it.

This navigation managed manually is, in this demo site, the one on the left. The one on the right is generated automatically, from the titles of paragraphs, and concerns the content of the current page only. It is implemented by the UI.

Navigation in the current page

The UI can offer navigation, generated automatically.

Differentiated navigation

Reminder
A component is defined by the antora.yml playbook which will be found at its root. This in turn references the navigation file, typically nav.adoc.

When a component is instantiated in several sites, you may want to differentiate the navigation of each of the instances.

This is typically what you might want to do with course materials: scroll down the navigation (on the left) progressively according to the progress of the course (to avoid exposing the entire course all at once).

This can be achieved via the StartPath key of the site playbook, which points to a directory of the component which will be its entry point.

For example, let’s take 2 sites master and computer license both composed of a common component.

We then create 2 sub-directories in the component, for example start_master and start_licence, each containing an antora.yml playbook that references a nav.adoc navigation also in this subdirectory. We then reference, via the StartPath key of the playbook of each of these 2 sites, the appropriate start_* sub-directory.

This is the easiest way to manage several independent navigations for the same component. Another way would be to skip StartPath and do this with git branches, one branch per promo.