From 667e11c4ec3835d959aab1797647bd0a49869674 Mon Sep 17 00:00:00 2001 From: etienne Date: Tue, 21 Oct 2014 23:35:24 +0200 Subject: Init commit --- content/extras/menus.md | 178 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 content/extras/menus.md (limited to 'content/extras/menus.md') diff --git a/content/extras/menus.md b/content/extras/menus.md new file mode 100644 index 0000000..57d87c0 --- /dev/null +++ b/content/extras/menus.md @@ -0,0 +1,178 @@ +--- +date: 2014-05-14T02:36:37Z +menu: + main: + parent: extras +next: /extras/permalinks +prev: /extras/livereload +title: Menus +weight: 20 +--- + +Hugo has a simple yet powerful menu system that permits content to be +placed in menus with a good degree of control without a lot of work. + +Some of the features of Hugo Menus: + +* Place content in one or many menus +* Handle nested menus with unlimited depth +* Create menu entries without being attached to any content +* Distinguish active element (and active branch) + +## What is a menu? + +A menu is a named array of menu entries accessible on the site under +`.Site.Menus` by name. For example, if I have a menu called `main`, I would +access it via `.Site.Menus.main`. + +A menu entry has the following properties: + +* **Url** string +* **Name** string +* **Menu** string +* **Identifier** string +* **Pre** template.HTML +* **Post** template.HTML +* **Weight** int +* **Parent** string +* **Children** Menu + +And the following functions: + +* **HasChildren** bool + +Additionally there are some relevant functions available on the page: + +* **IsMenuCurrent** (menu string, menuEntry *MenuEntry ) bool +* **HasMenuCurrent** (menu string, menuEntry *MenuEntry) bool + + +## Adding content to menus + +Hugo supports a couple of different methods of adding a piece of content +to the front matter. + +### Simple + +If all you need to do is add an entry to a menu, the simple form works +well. + +**A single menu:** + + --- + menu: "main" + --- + +**Multiple menus:** + + --- + menu: ["main", "footer"] + --- + + +### Advanced + +If more control is required, then the advanced approach gives you the +control you want. All of the menu entry properties listed above are +available. + + --- + menu: + main: + parent: 'extras' + weight: 20 + --- + + +## Adding (non-content) entries to a menu + +You can also add entries to menus that aren’t attached to a piece of +content. This takes place in the sitewide [config file](/overview/configuration). + +Here’s an example (in TOML): + + [[menu.main]] + name = "about hugo" + pre = "" + weight = -110 + identifier = "about" + [[menu.main]] + name = "getting started" + pre = "" + weight = -100 + +Here’s an example (in YAML): + + --- + menu: + main: + - Name: "about hugo" + Pre: "" + Weight: -110 + Identifier: "about" + - Name: "getting started" + Pre: "" + Weight: -100 + --- + +## Nesting + +All nesting of content is done via the `parent` field. + +The parent of an entry should be the identifier of another entry. +Identifier should be unique (within a menu). + +The following order is used to determine identity Identifier > Name > +LinkTitle > Title. This means that the title will be used unless +linktitle is present, etc. In practice Name and Identifier are never +displayed and only used to structure relationships. + +In this example, the top level of the menu is defined in the config file +and all content entries are attached to one of these entries via the +`parent` field. + +## Rendering menus + +Hugo makes no assumptions about how your rendered HTML will be +structured. Instead, it provides all of the functions you will need to be +able to build your menu however you want. + + +The following is an example: + + + + -- cgit v1.3