Navigation Menus and Files


    Component Selector Menu

    The products and services listed in the custom component selector dropdown menu are provided by the header-content.hbs template in the site’s UI project.

    Component Version Selector Menu

    The component name and version numbers listed in the version selector menu are generated from the title and version keys in the antora.yml file corresponding to that component version.

    Component Menu

    A component menu is the navigation displayed on the left side of the page when a visitor enters the documentation for a component. This menu is created from the Navigation Files registered in that component’s antora.yml file. The order the files are registered is the order their contents are displayed in the menu.

    The breadcrumbs listed at the top of a page are computed from the parent entry link text in the navigation file.

    On This Page Sidebar

    A page’s heading 2 section titles are displayed in the On This Page sidebar located on the right side of the page.

    When you want visitors to locate a page using the Component Menu, you must add a cross reference (xref) to that page in the appropriate navigation file. A navigation file can also include links to external URLs and other content, such as icons and normal text.

    Requirements, Best Practices, and Styles

    • A module can have no navigation file, one navigation file, or many navigation files.

    • If a module does have one or more navigation files, store the file(s) at the base of the module, e.g., modules/ROOT/nav.adoc, modules/contribute/nav.adoc.

    • In order to be published in a component menu, a navigation file must be registered in a component descriptor (antora.yml).

    • A navigation file must use the AsciiDoc file extension and is typically named nav.adoc.

    • A navigation file must contain at least one unordered AsciiDoc list.

    • The Couchbase documentation starts each list with a category title. See Update a Navigation File to learn how to create category titles and list items.

      • Use title case for category titles. Write “and” as an ampersand (&).

    • Use the cross reference macro (xref) to link to documentation pages. See Xrefs for navigation xref and link text examples.

      • Use title case for the link text in list items. Write “and” as and.