Working with menus

Menus are optional; not all themes will necessarily use a menu, and you don't have to fill it in if you don't want to. Having said that, if you do, you'll need to know what to do.

The file format

Open the content-demo/menu.txt file and compare what you can see to the menu that's visible in the browser.

You'll notice that each line in the file refers to the path to one of the files in the pages directory, with the file extension removed. You'll also notice that a menu item can have nested menu items beneath it, and that each sub level is indented by two spaces.

So you could have a menu.txt file that looked like this:

/
blog
docs
  marking-up-pages
    examples/using-markdown
    examples/using-textile
    examples/using-haml
    adding-attachments
  menu-editing
  publishing-a-feed
support
  faq
  knowledge-base
about
signup

/ is special and refers to the home page. All the other lines in that file refer to the path of one of the pages on your site, relative to the home page.

What gets displayed?

The entire menu doesn't necessarily have to be displayed on the page at once; you can pluck out a small section of the hierarchy (such as just the docs or support sections) and render that on the page.

The primary navigation at the top of this page, and the documentation menu in the sidebar were both rendered from this menu.txt file.

Nesta provides you with helper methods for rendering the HTML.

It's probably most easily understood by having a look at an example. The documentation menu in the sidebar of this page (over there on the right) was rendered by this snippet of Haml:

%nav.categories
  - display_menu(Nesta::Menu.for_path('/docs'), :class => "menu", :levels => 3)

The display_menu method expects at least one argument; a Ruby object that describes the menu hierarchy, as created by Nesta::Menu.for_path.

The display_menu method also takes an optional hash of options. The keys of the hash are:

  • :class -- Sets the HTML class of the top level <ul> tag that is generated to hold the menu items.
  • :levels -- Controls how deep into a nested menu structure you want to go; if it's greater than one (and your menu.txt file contains a nested hierarchy) you'll get <ul> tags for your submenus of your submenus. Defaults to 2.

Take a look at how the menu.txt file for nestacms.com was used to render all the menus on the site: