---
title: "Main menu of a TYPO3 documentation manual"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:rest-menu-hierachy"
source: "Reference/ReStructuredText/Menus/MenuHierarchy.rst"
rendered: "2026-09-22T14:34:53+00:00"
---

# Main menu of a TYPO3 documentation manual {#rest-menu-hierachy}

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 {#menu-automatic}

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**

```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 {#menu-semi-automatic}

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**

```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](https://docs.typo3.org/permalink/h2document:init-command)
to create a new ReST documentation we prepared such a menu for you.

## Manual menu using the toctree directive {#menu-manual}

You can define what should be included in the menu with the
[..  toctree::](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-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 {#menu-hidden}

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.

```rst
..  toctree::
    :hidden:

    Introduction/Index
    Configuration/Index
```

### `:titlesonly:` and `:maxdepth:` options {#menu-titlesonly}

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.

```rst
..  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 {#menu-rules}

Each `.rst` file that is included in the menu **must** have a page title and
should have a short
[navigation title](https://docs.typo3.org/permalink/h2document:navigation-title).

**Documentation/Introduction.rst**

```plaintext
:navigation-title: Main menu

..  include:: /Includes.rst.txt
..  _rest-menu-hierachy:

=========================================
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.

```

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](https://docs.typo3.org/permalink/h2document:rest-orphans).

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.