Main menu of a TYPO3 documentation manual

A manual consisting of more then one page should have a menu displayed on the left side of each page.

There are different strategies to get such a menu:

Automatically created alphabetic menu

If you do not want to deal with creating menus you can use the automatic menu.

Add the following option to the <guides> tag in your Documentation/guides.xml:

Documentation/guides.xml

<guides
    automatic-menu="true"
    <!-- ... -->

Using the .. toctree:: directive takes no effect in adjusting the menu then. When you use the automatic menu you cannot influence the order in the menu.

Semi-automatic menu

If you want to display some pages on top (like installation and introduction) but list all other pages automatically you can use a .. toctree:: directive with a glob pattern on your start page:

Documentation/Index.rst

..  toctree::
    :glob:
    :hidden:

    Introduction
    Installation
    Usage/Index
    *
    */Index

The menu will now contain first the listed pages, then all other .rst files in the root directory, then all Index.rst files in subdirectories. If you have additional .rst files in sub directories, you need to add such a toctree to the Index.rst in the sub directory.

If you use the The init command to create a new ReST documentation we prepared such a menu for you.

Manual menu using the toctree directive

You can define what should be included in the menu with the .. toctree:: directive. Only .rst files that are included in a toctree, are included in the menu.

The toctree directive can also be used to display a table of contents on current page (if :hidden: is not added in toctree).

The first headline of an .rst file is its "doctitle". That is the document's title property. The title and the following headlines are used for cross-references and appear in menus and table of contents.

`:hidden:` option

If you do not want to display the menu in the place where the toctree is defined use the :hidden: option. The toctree will only be used to define the right hand menu then.

..  toctree::
    :hidden:

    Introduction/Index
    Configuration/Index

`:titlesonly:` and `:maxdepth:` options

If the menu is not hidden by default all headlines from the included pages will be displayed. If you use the option :titlesonly: only the page titles are displayed.

..  toctree::
    :glob:
    :titlesonly:
    :maxdepth: 2

    *

You can limit the number of submenu points to be displayed in the place the menu was entered by using option :maxdepth:. Neither option influences the right hand menu.

General rules for using pages

Each .rst file that is included in the menu must have a page title and should have a short navigation title.

If a page should not be included in the menu it must be marked as :orphan: in the first line. Orphaned pages are not included in semi-automatic menus with the :glob: option. See Orphaned pages.

Each non orphaned page must be included in the menu exactly once. Including the same page in multiple pages in the menu will cause warnings and might produce unexpected results.