---
title: Webgen::Tag::Menu
used_options:
  - tag.menu.used_nodes
  - tag.menu.start_level
  - tag.menu.min_levels
  - tag.menu.max_levels
  - tag.menu.show_current_subtree_only
  - tag.menu.nested
---
## Description

The menu tag builds a seemingly simple menu using HTML lists. However, it is very flexible due to
its many options that let you decide every detail of the menu.

> The menu is constructed using HTML lists with `ul` and `li` tags.  However, the menu normally
> looks better if no discs are shown for the menu items (using the CSS directive `list-style-type:
> none`).
{.information}

It uses the meta information `in_menu` and `sort_info` to determine which nodes should be in the
menu and how they should be ordered. A separate menu tree is then created from all nodes for each
language.

By setting the option `tag.menu.used_nodes` to `fragments`, the menu tag can also be used for
generating an in-page content menu of all the header sections.

> When using the option value `files` for `tag.menu.used_nodes`, all nodes which are only in the
> menu because they have fragment nodes beneath them are not included in the menu.
{.exclamation}

The rendered menu consists of `ul` and `li` tags and the links (or `span` elements) to the menu
entries . The `li` tags have special CSS classes set for styling. These CSS class names are as
follows:

* `webgen-menu-levelNUMBER`: Set on all menu items and can be used to style specific menu levels
  only. `NUMBER` is replaced with the actual menu level, so the first level menu entries will get a
  `webgen-menu-level1` class.
* `webgen-menu-submenu`: Set if the menu item contains sub menu items.
* `webgen-menu-submenu-inhierarchy`: Set if the menu item contains sub menu items and it is in the
  sub tree of the rendered node.
* `webgen-menu-item-selected`: Set if the menu item corresponds to the rendered node.

The option `tag.menu.nested` decides whether a nested menu or a non-nested is generated. When
setting this option to `false` you need to ensure that `tag.menu.show_current_subtree_only` is set
to `true` and `tag.menu.min_levels` is set to `1`. Both ensure that no other subtree obfuscates the
menu.

> Set `tag.menu.nested` to `false` if you want to generate, for example, a horizontal menu, ie. a
> menu that has one horizontal bar for each menu level.
{.information}

## "Static" Menus

It is also possible to define a "static" menu or to augment the dynamic menu with static entries by
using virtual files. They can be used to structure the menu the way you like it. This way it is also
possible to add one page under two different headings:

    features.en.html:
      in_menu: true
      title: Features
      url: index.en.html#features

    newdir:
      sort_info: 2

    newdir/new.en.html:
      sort_info: 1
      in_menu: true
      url: ../features.en.html

There is no need to specify `in_menu` for `newdir` since a page under the directory is in the
menu. Also be aware that you need to set the language explicitly if a file should only appear in the
menu for a specific language. Otherwise it appears in every menu. The `url` specifies the file that
should be shown when clicked on the generated link.

A completely "static" menu can be generated by only using virtual directories and files and not
setting `in_menu` for any other node.

## Examples

<table class="examples">
<tr>
  <th>Usage</th><th>Output</th>
</tr>
<tr>
  <td>\{menu: }</td>
  <td>{menu:}</td>
</tr>
<tr>
  <td>\{menu: {used_nodes: all}}</td>
  <td>{menu: {used_nodes: all}}</td>
</tr>
<tr>
  <td>\{menu: {used_nodes: files}}</td>
  <td>{menu: {used_nodes: files}}</td>
</tr>
<tr>
  <td>\{menu: {used_nodes: fragments}}</td>
  <td>{menu: {used_nodes: fragments}}</td>
</tr>
<tr>
  <td>\{menu: {used_nodes: all, nested: false}}</td>
  <td>{menu: {used_nodes: all, nested: false}}</td>
</tr>
</table>