mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
234 lines
7 KiB
Markdown
234 lines
7 KiB
Markdown
---
|
||
lastmod: 2015-08-04
|
||
date: 2014-05-14T02:36:37Z
|
||
toc: true
|
||
menu:
|
||
main:
|
||
parent: extras
|
||
next: /extras/pagination
|
||
prev: /extras/livereload
|
||
title: Menus
|
||
---
|
||
|
||
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.
|
||
|
||
|
||
*TIP:* If all you want is a simple menu for your sections, see [Section Menu for "the Lazy Blogger"]({{< relref "#section-menu-for-the-lazy-blogger" >}}).
|
||
|
||
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`.
|
||
|
||
If you make use of the [multilingual feature]({{< relref "content/multilingual.md#menus">}}) you can define menus language independent.
|
||
|
||
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 `config.toml`:
|
||
|
||
[[menu.main]]
|
||
name = "about hugo"
|
||
pre = "<i class='fa fa-heart'></i>"
|
||
weight = -110
|
||
identifier = "about"
|
||
url = "/about/"
|
||
[[menu.main]]
|
||
name = "getting started"
|
||
pre = "<i class='fa fa-road'></i>"
|
||
weight = -100
|
||
url = "/getting-started/"
|
||
|
||
And the equivalent example `config.yaml`:
|
||
|
||
---
|
||
menu:
|
||
main:
|
||
- Name: "about hugo"
|
||
Pre: "<i class='fa fa-heart'></i>"
|
||
Weight: -110
|
||
Identifier: "about"
|
||
URL: "/about/"
|
||
- Name: "getting started"
|
||
Pre: "<i class='fa fa-road'></i>"
|
||
Weight: -100
|
||
URL: "/getting-started/"
|
||
---
|
||
|
||
|
||
**NOTE:** The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the `URL` is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`.
|
||
|
||
## 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 an 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:
|
||
|
||
<!--sidebar start-->
|
||
<aside>
|
||
<div id="sidebar" class="nav-collapse">
|
||
<!-- sidebar menu start-->
|
||
<ul class="sidebar-menu">
|
||
{{ $currentPage := . }}
|
||
{{ range .Site.Menus.main }}
|
||
{{ if .HasChildren }}
|
||
|
||
<li class="sub-menu{{if $currentPage.HasMenuCurrent "main" . }} active{{end}}">
|
||
<a href="javascript:;" class="">
|
||
{{ .Pre }}
|
||
<span>{{ .Name }}</span>
|
||
<span class="menu-arrow arrow_carrot-right"></span>
|
||
</a>
|
||
<ul class="sub">
|
||
{{ range .Children }}
|
||
<li{{if $currentPage.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.URL}}"> {{ .Name }} </a> </li>
|
||
{{ end }}
|
||
</ul>
|
||
{{else}}
|
||
<li>
|
||
<a href="{{.URL}}">
|
||
{{ .Pre }}
|
||
<span>{{ .Name }}</span>
|
||
</a>
|
||
{{end}}
|
||
</li>
|
||
{{end}}
|
||
<li> <a href="https://github.com/spf13/hugo/issues" target="blank">Questions and Issues</a> </li>
|
||
<li> <a href="#" target="blank">Edit this Page</a> </li>
|
||
</ul>
|
||
<!-- sidebar menu end-->
|
||
</div>
|
||
</aside>
|
||
<!--sidebar end-->
|
||
|
||
> **Note**: use the `absLangURL` or `relLangURL` if your theme makes use of the [multilingual feature]({{< relref "content/multilingual.md" >}}). In contrast to `absURL` and `relURL` it adds the correct language prefix to the url. [Read more]({{< relref "templates/functions.md#urls" >}}).
|
||
|
||
## Section Menu for "the Lazy Blogger"
|
||
|
||
To enable this menu, add this to your site config, i.e. `config.toml`:
|
||
|
||
```
|
||
SectionPagesMenu = "main"
|
||
```
|
||
|
||
The menu name can be anything, but take a note of what it is.
|
||
|
||
This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this:
|
||
|
||
```
|
||
<nav class="sidebar-nav">
|
||
{{ $currentPage := . }}
|
||
{{ range .Site.Menus.main }}
|
||
<a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{.URL}}">{{ .Name }}</a>
|
||
{{ end }}
|
||
</nav>
|
||
|
||
```
|
||
|
||
In the above, the menu item is marked as active if on the current section's list page or on a page in that section.
|
||
|
||
The above is all that's needed. But if you want custom menu items, e.g. changing weight or name, you can define them manually in the site config, i.e. `config.toml`:
|
||
|
||
```
|
||
[[menu.main]]
|
||
name = "This is the blog section"
|
||
weight = -110
|
||
identifier = "blog"
|
||
url = "/blog/"
|
||
|
||
```
|
||
|
||
**Note** that the `identifier` must match the section name.
|
||
|