Merge branch 'rmetzler-menu-link-title'

content/templates/menu-templates.md

@@ -9,6 +9,7 @@ categories: [templates]
 keywords: [lists,sections,menus]
 menu:
   docs:
+    title: "how to use menus in templates"
     parent: "templates"
     weight: 130
 weight: 130
@@ -78,18 +79,22 @@ This will create a menu with all the sections as menu items and all the sections
 <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>
+    <a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{ .URL }}" title="{{ .Title }}">{{ .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`:
+
+## Site Config menus
+
+The above is all that's needed. But if you want custom menu items, e.g. changing weight, name, or link title attribute, you can define them manually in the site config, i.e. `config.toml`:
 
 ```
 [[menu.main]]
     name = "This is the blog section"
+    title = "blog section"
     weight = -110
     identifier = "blog"
     url = "/blog/"
@@ -98,3 +103,55 @@ The above is all that's needed. But if you want custom menu items, e.g. changing
 {{% note %}}
 The `identifier` *must* match the section name.
 {{% /note %}}
+
+## Menu Entries from the Page's front matter
+
+It's also possible to create menu entries from the page (i.e. the `.md`-file).
+
+Here is a `yaml` example:
+
+```
+---
+title: Menu Templates
+linktitle: Menu Templates
+menu:
+  docs:
+    title: "how to use menus in templates"
+    parent: "templates"
+    weight: 130
+---
+...
+```
+
+{{% note %}}
+You can define more than one menu. It also doesn't have to be a complex value,
+`menu` can also be a string, an array of strings, or an array of complex values
+like in the example above.
+{{% /note %}}
+
+### Using .Page in Menus
+
+If you use the front matter method of defining menu entries, you'll get access to the `.Page` variable.
+This allows to use every variable that's reachable from the [page variable](/variables/page/).
+
+This variable is only set when the menu entry is defined in the page's front matter.
+Menu entries from the site config don't know anything about `.Page`.
+
+That's why you have to use the go template's `with` keyword or something similar in your templating language.
+
+Here's an example:
+
+```
+<nav class="sidebar-nav">
+  {{ range .Site.Menus.main }}
+    <a href="{{ .URL }}" title="{{ .Title }}">
+      {{- .Name -}}
+      {{- with .Page -}}
+        <span class="date">
+        {{- dateFormat " (2006-01-02)" .Date -}}
+        </span>
+      {{- end -}}
+    </a>
+  {{ end }}
+</nav>
+```

content/variables/menus.md

@@ -10,6 +10,7 @@ keywords: [menus]
 draft: false
 menu:
   docs:
+    title: "variables defined by a menu entry"
     parent: "variables"
     weight: 50
 weight: 50
@@ -26,6 +27,22 @@ The [menu template][] has the following properties:
 .Name
 : string
 
+.Title
+: string
+
+This is a link title, meant to be used in `title`-Attributes of the menu's `<a>`-tags.
+By default it returns `.Page.LinkTitle`, as long as the menu entry was created
+through the page's front matter and not through the site config.
+Setting it explicitly in the site config or the page's front matter overrides this behaviour.
+
+.Page
+: [Page Object](/variables/page/)
+
+The `.Page` variable holds a reference to the page.
+It's only set when the menu entry is created from the page's front matter,
+not when it's created from the site config.
+
+
 .Menu
 : string
 
@@ -47,4 +64,4 @@ The [menu template][] has the following properties:
 .Children
 : Menu
 
-[menu template]: /templates/menu-templates/
+[menu template]: /templates/menu-templates/

content/variables/page.md

@@ -10,6 +10,7 @@ keywords: [pages]
 draft: false
 menu:
   docs:
+    title: "variables defined by a page"
     parent: "variables"
     weight: 20
 weight: 20