Navigation Menus and Structure

While using this website, you may notice several things about this documentation theme. It contains multiple navigation menus: Site Navigation, Section Navigation, and Page Navigation.

The Site Navigation is along the top bar if your window is expanded, or collapsed along the left side under the label Site Navigation if your window is smaller.

The Section Navigation is along the left side of the screen if the window is expanded, or collapsed along the left side of the window under the label Section Navigation if your window is smaller. In the framework we are proposing, each project will have four sections - “Getting Started”, “User Guide”, “API Reference”, and “Developer Guide”. Each of these sections can have multiple pages and their own navigation. This structure (four sections), follows the [Diataxis model](https://diataxis.fr/) of documentation. You may choose to implement different sections in your documentation, but we use these as an example here.

This portion of the documentation describes how to achieve the different navigation types, and is applicable regardless of your section names.

The Page Navigation is along the right side of the screen if the window is expanded, and collapsed under the button next to the Search button in the upper right if your page is smaller.

Each of these navigation types is separately set, with the Site and Section navigation being based on your documentation structure and Table of Contents directives.

This page outlines each type of Navigation menu and how to configure your sections.

Site Navigation

Site navigation (along the top bar) is determined by the entries in the Table of Contents (TOC) on the main index.rst or index.md file.

For example, the TOC for this site is shown below:

.. toctree::
    :hidden:
    :titlesonly:

    getting_started/index
    user_guide/index
    api/index
    developer_guide/index

The TOC shown above links to index pages in directories for each section. This allows for section navigation along the left side of the page. The Section Navigation section, below describes the directory structure and how to configure section navigation.

TOC Options

For the front page TOC, we recommend using the options :hidden:, which will hide the table of contents from the front page, and :titlesonly:. These options still allow the main site navigation bar along the top of the page to be populated.

Section Navigation

Section navigation is acheived by creating a directory with an index.rst or `index.md file which contains a table of contents (this page must be included in the main table of contents described previously to be indexed).

To achieve the section navigation in the left sidebar, we suggest grouping your documentation into different folders representing the sections. You should add the rst for section pages within these folders, and link to them in the section TOC.

For example, for this documentation project, the directory structure for this section is shown below:

getting_started/
├── docs_structure.rst
├── front_page.rst
├── index.rst
└── installation.rst

The section TOC for this page in the file index.rst

.. toctree::
    :maxdepth: 2

    installation
    docs_structure
    front_page

Page Navigation

Page navigation (right sidebar) is based on subheaders on the page. Each entry in the section navigation represents a level 2 header in this document.

Third Level Headers

You can also see third-level headers in this side-menu.

Fourth Level Headers

Fourth Level Headers are not shown on the page navigation.