diff --git a/exampleSite/content/authoring/frontmatter/menus/_index.en.md b/exampleSite/content/authoring/frontmatter/menus/_index.en.md index 96450e80c7..6d7308f119 100644 --- a/exampleSite/content/authoring/frontmatter/menus/_index.en.md +++ b/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). diff --git a/exampleSite/content/authoring/frontmatter/menus/_index.pir.md b/exampleSite/content/authoring/frontmatter/menus/_index.pir.md index bcee333c36..6d7308f119 100644 --- a/exampleSite/content/authoring/frontmatter/menus/_index.pir.md +++ b/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 >}} \ No newline at end of file diff --git a/exampleSite/content/configuration/sidebar/menus/_index.en.md b/exampleSite/content/configuration/sidebar/menus/_index.en.md index 1f0f4955ec..72f3ca78ee 100644 --- a/exampleSite/content/configuration/sidebar/menus/_index.en.md +++ b/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 diff --git a/exampleSite/content/introduction/releasenotes/7/1.en.md b/exampleSite/content/introduction/releasenotes/7/1.en.md index 08abb5fd3e..3e54ac4e20 100644 --- a/exampleSite/content/introduction/releasenotes/7/1.en.md +++ b/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. diff --git a/layouts/partials/_relearn/pageNext.gotmpl b/layouts/partials/_relearn/pageNext.gotmpl index 47a3b58fcd..0d8aa2b0e5 100644 --- a/layouts/partials/_relearn/pageNext.gotmpl +++ b/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 }} diff --git a/layouts/partials/_relearn/pagePrev.gotmpl b/layouts/partials/_relearn/pagePrev.gotmpl index fe94343978..6b659ff1f3 100644 --- a/layouts/partials/_relearn/pagePrev.gotmpl +++ b/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 = . }} diff --git a/layouts/partials/menu.html b/layouts/partials/menu.html index 6ecbce002b..1b1ded1207 100644 --- a/layouts/partials/menu.html +++ b/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 }}