menu: support for external links #148

exampleSite/content/authoring/frontmatter/menus/_index.en.md

@@ -2,8 +2,5 @@
 description = "Setting the behavior of the menus"
 title = "Menus"
 weight = 2
+menuPageRef = '/configuration/sidebar/menus'
 +++
-
-The theme can build menu trees from [the structure of your page files](authoring/structure) or from [Hugo's build in menu feature](https://gohugo.io/content-management/menus/).
-
-To keep all documentation for menus together, you can [find it in the configureation section](configuration/sidebar/menus).

exampleSite/content/authoring/frontmatter/menus/_index.pir.md

@@ -2,5 +2,5 @@
 description = "Setting the behavior of the menus"
 title = "Menus"
 weight = 2
+menuPageRef = '/configuration/sidebar/menus'
 +++
-{{< piratify >}}

exampleSite/content/configuration/sidebar/menus/_index.en.md

@@ -1,7 +1,7 @@
 +++
 categories = ["howto"]
 description = "Configure all things menus"
-frontmatter = ["alwaysopen", "collapsibleMenu", "linkTitle", "menuPost", "menuPre", "ordersectionsby", "sidebarmenus"]
+frontmatter = ["alwaysopen", "collapsibleMenu", "linkTitle", "menuPageRef", "menuPost", "menuPre", "menuUrl", "ordersectionsby", "sidebarmenus"]
 options = ["alwaysopen", "collapsibleMenu", "disableShortcutsTitle", "ordersectionsby",  "sidebarmenus"]
 title = "Menus"
 weight = 4
@@ -261,6 +261,42 @@ title = 'Documentation'
     ]
 {{< /multiconfig >}}
 
+## Displaying Arbitrary Links in a Page Menu
+
+You may have the need to add arbitrary links at some point in your menu that are initially not backed by a page. These are called crosslinks.
+
+Assume the following structure
+
+````plaintext
+content
+├── reference
+│   ├── ref-a.md
+│   ├── ref-b.md
+│   ├── ref-c.md
+│   └── _index_.md
+├── topic-blue.md
+├── topic-red.md
+├── topic-yellow.md
+└── _index_.md
+````
+
+You now want to include `ref-b` as separate entry after `topic-green` in your menu.
+
+For that create a new page with the following front matter
+
+{{< multiconfig fm=true file="content/topic-green.md" >}}
+title = 'Topic Green'
+menuPageRef = '/reference/ref-b'
+{{< /multiconfig >}}
+
+If you want to link to an external page instead, you can use `menuUrl` instead of `menuPageRef`.
+
+Pages defining a crosslink are never part of the arrow navigation and are skipped instead.
+
+So with the above example and alphabetical sorting of the menu entries, pressing {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} on `topic-blue` will skip the newly added `topic-green` and instead will load `topic-red`.
+
+Having sub pages below a page that defines a crosslink is undefined.
+
 ## Displaying Pages Exclusively in a Hugo Menu
 
 Sometimes you want to hide pages from the page menu but instead want to show them in a Hugo menu. For that you have two choices

exampleSite/content/introduction/releasenotes/7/1.en.md

@@ -23,3 +23,7 @@ weight = -1
   - apply the usual parameter `alwaysopen`, `collapsibleMenu`, etc. for all menu types
 
   You don't need to change anything in your existing installation as the old configuration is used as a default.
+
+### New
+
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Menus created by your page structure are now able to [contain arbitrary links](configuration/sidebar/menus#displaying-arbitrary-links-in-a-page-menu) inserted into the structure using the `menuUrl` or `menuPageRef` front matter.

layouts/partials/_relearn/pageNext.gotmpl

@@ -85,7 +85,7 @@
   {{- range $siblings }}
     {{- if eq . $currentNode }}
       {{- $currentFound = true }}
-    {{- else if $currentFound }}
+    {{- else if and $currentFound (not (or (eq .Title "") .Params.hidden .Params.menuUrl .Params.menuPageRef)) }}
       {{- $nextSibling = . }}
       {{- break }}
     {{- end }}
@@ -95,7 +95,7 @@
 
 {{- define "partials/inline/leftmost_descendant" }}
   {{- $leftmostVisible := "" }}
-  {{- if not (or (.Params.hidden) (eq .Title "")) }}
+  {{- if not (or (eq .Title "") .Params.hidden .Params.menuUrl .Params.menuPageRef) }}
     {{- if .RelPermalink }}
       {{- $leftmostVisible = . }}
     {{- else }}

layouts/partials/_relearn/pagePrev.gotmpl

@@ -62,7 +62,7 @@
   {{- range $siblings }}
     {{- if eq . $currentNode }}
       {{- break }}
-    {{- else if not (or (.Params.hidden) (eq .Title "")) }}
+    {{- else if not (or (eq .Title "") .Params.hidden .Params.menuUrl .Params.menuPageRef) }}
       {{- $previousSibling = . }}
     {{- end }}
   {{- end }}
@@ -73,7 +73,7 @@
   {{- $rightmostVisible := . }}
   {{- $pages := (partialCached "_relearn/pages.gotmpl" (dict "page" $rightmostVisible) $rightmostVisible.Path) | collections.Reverse }}
   {{- range $pages }}
-    {{- if not (or (.Params.hidden) (eq .Title "")) }}
+    {{- if not (or (eq .Title "") .Params.hidden .Params.menuUrl .Params.menuPageRef) }}
       {{- with partial "inline/rightmost_descendant" . }}
         {{- if .RelPermalink }}
           {{- $rightmostVisible = . }}

layouts/partials/menu.html

@@ -161,9 +161,27 @@
     {{- end }}
     {{- $title := partial "title.gotmpl" (dict "page" . "linkTitle" true) }}
     {{- $url := partial "permalink.gotmpl" (dict "to" .) }}
+    {{- $isCrosslink := false }}
+    {{- $target := "" }}
+    {{- if .Params.menuPageRef }}
+      {{- with site.Home.GetPage (.Params.menuPageRef) }}
+        {{- $url = partial "permalink.gotmpl" (dict "to" .) }}
+        {{- $isCrosslink = true }}
+      {{- end }}
+    {{- else if .Params.menuUrl }}
+      {{- $url = .Params.menuUrl }}
+      {{- $isCrosslink = true }}
+      {{- $u := urls.Parse $url }}
+      {{- if $u.IsAbs }}
+        {{- $target = "_blank" }}
+        {{- if isset site.Params "externallinktarget" }}
+          {{- $target = site.Params.externalLinkTarget }}
+        {{- end }}
+      {{- end }}
+    {{- end }}
     {{- $pre := partial "menu-pre.html" . }}
     {{- $post := partial "menu-post.html" . }}
-    {{- if $hasVisibleChildren }}
+    {{- if and $hasVisibleChildren (not $isCrosslink) }}
       {{- $isCollapsible := .Params.collapsibleMenu | default site.Params.collapsibleMenu }}
       {{- $currentAlwaysopen := .Params.alwaysopen | default $alwaysopen }}
       {{- if and (not $url) (not $isCollapsible) }}
@@ -173,7 +191,7 @@
       {{- $isOpen := or $currentAlwaysopen $isSelf $isAncestor }}
             <li class="{{if $isActive }}active {{end}}{{if (or $isSelf $isAncestor) }}parent {{end}}{{if $isHidden }}hidden {{end}}{{if not $url }}headless {{end}}{{if $currentAlwaysopen}}alwaysopen {{end}}" data-nav-id="{{ $url }}">
       {{- if $isCollapsible }}<input type="checkbox" id="R-section-{{ $entryId }}" aria-controls="R-subsections-{{ $entryId }}"{{ if $isOpen }} checked{{ end }}><label for="R-section-{{ $entryId }}"><i class="fa-fw fas fa-chevron-down"></i><i class="fa-fw fas fa-chevron-right"></i><span class="a11y-only">{{ T "Submenu" $title }}</span></label>{{ end }}
-      {{- if $url }}<a class="padding" href="{{ $url }}">{{ else }}<span class="padding">{{ end }}
+      {{- if $url }}<a class="padding" href="{{ $url }}"{{ if gt (len $target) 0 }} target="{{ $target }}"{{ end }}>{{ else }}<span class="padding">{{ end }}
       {{- $pre }}{{ $title }}{{ $post }}
       {{- if $url }}{{ if $showvisitedlinks }}<i class="fa-fw fas fa-check read-icon"></i>{{ end }}</a>{{ else }}</span>{{ end }}<ul id="R-subsections-{{ $entryId }}" class="collapsible-menu">
       {{- $defaultAlwaysopen := site.Params.alwaysopen | default true }}
@@ -190,8 +208,8 @@
         {{- end }}
       {{- end }}</ul></li>
     {{- else if $url }}
-            <li class="{{if $isActive }}active {{end}}{{if $isHidden }}hidden {{end}}{{if not $url }}headless {{end}}" data-nav-id="{{ $url }}">
-      {{- if $url }}<a class="padding" href="{{ $url }}">{{ else }}<span class="padding">{{ end }}
+            <li class="{{if $isActive }}active {{end}}{{if $isHidden }}hidden {{end}}{{if not $url }}headless {{end}}{{if $isCrosslink }}crosslink {{end}}" data-nav-id="{{ $url }}">
+      {{- if $url }}<a class="padding" href="{{ $url }}"{{ if gt (len $target) 0 }} target="{{ $target }}"{{ end }}>{{ else }}<span class="padding">{{ end }}
       {{- $pre }}{{ $title }}{{ $post }}
       {{- if $url }}{{ if $showvisitedlinks }}<i class="fa-fw fas fa-check read-icon"></i>{{ end }}</a>{{ else }}</span>{{ end }}</li>
     {{- end }}
@@ -283,6 +301,14 @@
     {{- end }}
     {{- $title := partial "menutitle.gotmpl" . }}
     {{- $url := partial "menupermalink.gotmpl" . }}
+    {{- $target := "" }}
+    {{- $u := urls.Parse $url }}
+    {{- if $u.IsAbs }}
+      {{- $target = "_blank" }}
+      {{- if isset site.Params "externallinktarget" }}
+        {{- $target = site.Params.externalLinkTarget }}
+      {{- end }}
+    {{- end }}
     {{- $pre := .Pre }}
     {{- $post := .Post }}
     {{- with .Page }}
@@ -299,7 +325,7 @@
       {{- $isOpen := or $currentAlwaysopen $isSelf $isAncestor }}
             <li class="{{if $isActive }}active {{end}}{{if (or $isSelf $isAncestor) }}parent {{end}}{{if $isHidden }}hidden {{end}}{{if not $url }}headless {{end}}{{if $currentAlwaysopen}}alwaysopen {{end}}" data-nav-id="{{ $url }}">
       {{- if $isCollapsible }}<input type="checkbox" id="R-section-{{ $entryId }}" aria-controls="R-subsections-{{ $entryId }}"{{ if $isOpen }} checked{{ end }}><label for="R-section-{{ $entryId }}"><i class="fa-fw fas fa-chevron-down"></i><i class="fa-fw fas fa-chevron-right"></i><span class="a11y-only">{{ T "Submenu" $title }}</span></label>{{ end }}
-      {{- if $url }}<a class="padding" href="{{ $url }}">{{ else }}<span class="padding">{{ end }}
+      {{- if $url }}<a class="padding" href="{{ $url }}"{{ if gt (len $target) 0 }} target="{{ $target }}"{{ end }}>{{ else }}<span class="padding">{{ end }}
       {{- $pre }}{{ $title }}{{ $post }}
       {{- if $url }}{{ if $showvisitedlinks }}<i class="fa-fw fas fa-check read-icon"></i>{{ end }}</a>{{ else }}</span>{{ end }}<ul id="R-subsections-{{ $entryId }}" class="collapsible-menu">
       {{- $defaultAlwaysopen := site.Params.alwaysopen | default true }}
@@ -317,7 +343,7 @@
       {{- end }}</ul></li>
     {{- else if $url }}
             <li class="{{if $isActive }}active {{end}}{{if $isHidden }}hidden {{end}}{{if not $url }}headless {{end}}" data-nav-id="{{ $url }}">
-      {{- if $url }}<a class="padding" href="{{ $url }}">{{ else }}<span class="padding">{{ end }}
+      {{- if $url }}<a class="padding" href="{{ $url }}"{{ if gt (len $target) 0 }} target="{{ $target }}"{{ end }}>{{ else }}<span class="padding">{{ end }}
       {{- $pre }}{{ $title }}{{ $post }}
       {{- if $url }}{{ if $showvisitedlinks }}<i class="fa-fw fas fa-check read-icon"></i>{{ end }}</a>{{ else }}</span>{{ end }}</li>
     {{- end }}

layouts/partials/meta.html

@@ -14,6 +14,19 @@
     {{- if not (and $title .RelPermalink (or (ne .Site.Params.disableSeoHiddenPages true) (not (partialCached "_relearn/pageIsHiddenSelfOrAncestor.gotmpl" (dict "page" . "to" .Site.Home) .Path .Site.Home.Path) ) ) ) }}
     <meta name="robots" content="noindex, nofollow, noarchive, noimageindex">
     {{- end }}
+    {{- $url := "" }}
+    {{- if .Params.menuPageRef }}
+        {{- with site.Home.GetPage (.Params.menuPageRef) }}
+            {{- $url = partial "permalink.gotmpl" (dict "to" .) }}
+        {{- else }}
+            {{- warnf "%q: WARNING: page '%s' not found for 'menuPageRef' parameter" .File.Filename .Params.menuPageRef }}
+        {{- end }}
+    {{- else if .Params.menuUrl }}
+        {{- $url = .Params.menuUrl }}
+    {{- end }}
+    {{- if $url }}
+    <meta http-equiv="refresh" content="0; url={{ $url }}">
+    {{- end }}
     <meta name="description" content="{{ with trim (or .Description .Summary | plainify | htmlUnescape) "\n\r\t " }}{{ . }}{{ end }}">
     {{- $authorName := partialCached "_relearn/authorName.gotmpl" . }}
     <meta name="author" content="{{ $authorName }}">

layouts/partials/version.txt

@@ -1 +1 @@
-7.0.1+9797e071ae2d359be854f02d76ac3a9e8cd22f72
+7.0.1+40a55a3e52be6798651fabb67c3fa4b8dc26d6e6