mirror of
https://github.com/McShelby/hugo-theme-relearn.git
synced 2024-11-22 15:27:54 +00:00
docs: merge menu docs #423
This commit is contained in:
Sören Weber
parent
4190479458
commit
0938e8bd2e
15 changed files with 90 additions and 209 deletions
|
|
@ -31,8 +31,7 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
|
|||
- [Chapter and site-wide printing capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/outputformats#print-support)
|
||||
- [Versatile search options: in-page, popup, and dedicated search page](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search)
|
||||
- [Customizable top bar buttons](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/topbar)
|
||||
- [Nested menus](https://mcshelby.github.io/hugo-theme-relearn/authoring/frontmatter/menu)
|
||||
- [Configurable menus](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/shortcutmenu)
|
||||
- [Configurable menus](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/menus)
|
||||
- [Support for hidden pages](https://mcshelby.github.io/hugo-theme-relearn/configuration/content/hidden)
|
||||
- [Comprehensive taxonomy support](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/taxonomy)
|
||||
- [Social media integration](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/meta#social-media-images)
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
+++
|
||||
categories = ["howto"]
|
||||
description = "Behavior of the navigation menu"
|
||||
frontmatter = ["alwaysopen", "collapsibleMenu", "linkTitle", "menuPost", "menuPre", "ordersectionsby"]
|
||||
options = ["alwaysopen", "collapsibleMenu", "ordersectionsby"]
|
||||
title = "Navigation Menu"
|
||||
weight = 2
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
+++
|
||||
description = "Setting the behavior of the menus"
|
||||
title = "Menus"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
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).
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
+++
|
||||
description = "Setting the behavior of the menus"
|
||||
title = "Menus"
|
||||
weight = 2
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,10 +1,10 @@
|
|||
+++
|
||||
categories = ["howto"]
|
||||
description = "Setting the behavior of the menus"
|
||||
description = "Configure all things menus"
|
||||
frontmatter = ["alwaysopen", "collapsibleMenu", "linkTitle", "menuPost", "menuPre", "ordersectionsby", "sidebarmenus"]
|
||||
options = ["alwaysopen", "collapsibleMenu", "ordersectionsby", "sidebarmenus"]
|
||||
options = ["alwaysopen", "collapsibleMenu", "disableShortcutsTitle", "ordersectionsby", "sidebarmenus"]
|
||||
title = "Menus"
|
||||
weight = 2
|
||||
weight = 4
|
||||
+++
|
||||
|
||||
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/).
|
||||
|
|
@ -124,6 +124,8 @@ For this, open `content/first-chapter/first-page/_index.md` and add the followin
|
|||
|
||||
Just don't give your parent menu entry configuration a `url` or `pageRef`. See the [next section](#title-for-menus) for a special case.
|
||||
|
||||
If you want to learn how to configure different Hugo menus for each language, [see the official docs](https://gohugo.io/content-management/multilingual/#menus).
|
||||
|
||||
{{< multiconfig fm=true >}}
|
||||
[[menu.addendum]]
|
||||
name = 'Parent 1'
|
||||
|
|
@ -156,6 +158,8 @@ If you don't want to fiddle around with your translation files, you also have th
|
|||
|
||||
In this case, the `title` or `name` is taken for the menu heading.
|
||||
|
||||
If you want to learn how to configure different Hugo menus for each language, [see the official docs](https://gohugo.io/content-management/multilingual/#menus).
|
||||
|
||||
{{< multiconfig fm=true >}}
|
||||
[[menu.addendum]]
|
||||
name = 'A Menu Title for the Whole Menu'
|
||||
|
|
@ -173,6 +177,24 @@ In this case, the `title` or `name` is taken for the menu heading.
|
|||
weight = 2
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Title for the Predefined Shortcut Menu
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, the predefined shortcut menu has a the title _More_ (in the English translation).
|
||||
|
||||
You can disable this title with `disableShortcutsTitle=true`.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableShortcutsTitle = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
To change the title, override your translation file.
|
||||
|
||||
````toml {title="i18n/en.toml"}
|
||||
[shortcuts-menuTitle]
|
||||
other = "Other Great Stuff"
|
||||
````
|
||||
|
||||
## Defining Sidebar Menus
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Menus are defined using the `sidebarmenus` option.
|
||||
|
|
@ -181,8 +203,8 @@ You can define as many menus, as you like. If you don't overwrite this option, t
|
|||
|
||||
{{< multiconfig >}}
|
||||
sidebarmenus = [
|
||||
{ type = 'page', identifier = 'home', main = true, disableTitle = true, pageRef = '' },
|
||||
{ type = 'menu', identifier = 'shortcuts', main = false, disableTitle = false },
|
||||
{ type = 'page', identifier = 'home', main = true, disableTitle = true, pageRef = '' },
|
||||
{ type = 'menu', identifier = 'shortcuts', main = false, disableTitle = false },
|
||||
]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
|
|
@ -238,3 +260,32 @@ title = 'Documentation'
|
|||
{ type = 'page', identifier = 'docs', pageRef = '/docs' },
|
||||
]
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## 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
|
||||
|
||||
1. Create a [headless branch bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle), `_index.md` in its own folder with the below front matter. The branch bundle will **not** be contained in the sitemap.
|
||||
|
||||
{{< multiconfig fm=true file="content/showcase/_index.en.md" >}}
|
||||
title = 'Showcase'
|
||||
[_build]
|
||||
render = 'always'
|
||||
list = 'never'
|
||||
publishResources = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
2. Or, put a child page _inside_ a headless branch bundle with the following front matter in the bundle. This causes the child but not the branch bundle to be contained in the sitemap.
|
||||
|
||||
{{< multiconfig fm=true file="content/more/_index.en.md" >}}
|
||||
[_build]
|
||||
render = 'never'
|
||||
list = 'never'
|
||||
publishResources = false
|
||||
{{< /multiconfig >}}
|
||||
|
||||
The child page can be any type of content.
|
||||
|
||||
{{< multiconfig fm=true file="content/more/credits_index.en.md" >}}
|
||||
title = 'Credits'
|
||||
{{< /multiconfig >}}
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
+++
|
||||
categories = ["howto"]
|
||||
description = "Configure all things menus"
|
||||
frontmatter = ["alwaysopen", "collapsibleMenu", "linkTitle", "menuPost", "menuPre", "ordersectionsby", "sidebarmenus"]
|
||||
options = ["alwaysopen", "collapsibleMenu", "disableShortcutsTitle", "ordersectionsby", "sidebarmenus"]
|
||||
title = "Menus"
|
||||
weight = 4
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -1,176 +0,0 @@
|
|||
+++
|
||||
categories = ["howto"]
|
||||
description = "Add additional shortcut links to the sidebar"
|
||||
options = ["disableShortcutsTitle"]
|
||||
title = "Shortcut Menu"
|
||||
weight = 4
|
||||
+++
|
||||
|
||||
The sidebar contains your content's navigation menu, but you can also add extra menu entries or shortcuts in a separate section.
|
||||
|
||||
For internal links, use the `pageRef` property instead of `url`. Learn more about [Hugo's menu configuration](https://gohugo.io/content-management/menus/#define-in-site-configuration).
|
||||
|
||||
## Title
|
||||
|
||||
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, the shortcut menu has a title ("_More_" in English).
|
||||
|
||||
You can disable this title with `disableShortcutsTitle=true`.
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[params]
|
||||
disableShortcutsTitle = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
To change the title, update your local i18n translation file.
|
||||
|
||||
````toml {title="i18n/en.toml"}
|
||||
[shortcuts-menuTitle]
|
||||
other = "Other Great Stuff"
|
||||
````
|
||||
|
||||
## Single Language Example
|
||||
|
||||
Edit `hugo.toml` and add `[[menu.shortcuts]]` entries for each link:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[[menu.shortcuts]]
|
||||
pre = '<i class="fa-fw fab fa-github"></i> '
|
||||
name = 'GitHub Repo'
|
||||
url = 'https://github.com/McShelby/hugo-theme-relearn'
|
||||
weight = 10
|
||||
|
||||
[[menu.shortcuts]]
|
||||
name = 'Showcases'
|
||||
pageRef = '/showcase'
|
||||
weight = 20
|
||||
|
||||
[[menu.shortcuts]]
|
||||
name = 'Credits'
|
||||
pageRef = '/more/credits'
|
||||
weight = 30
|
||||
|
||||
[[menu.shortcuts]]
|
||||
pre = '<i class="fa-fw fas fa-tags"></i> '
|
||||
name = 'Tags'
|
||||
pageRef = '/tags'
|
||||
weight = 40
|
||||
|
||||
[[menu.shortcuts]]
|
||||
pre = '<i class="fa-fw fas fa-layer-group"></i> '
|
||||
name = 'Categories'
|
||||
pageRef = '/categories'
|
||||
weight = 50
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Multilingual Example
|
||||
|
||||
For multilingual sites, set different menus for each language in `hugo.toml`:
|
||||
|
||||
{{< multiconfig file=hugo >}}
|
||||
[languages]
|
||||
[languages.en]
|
||||
title = 'Hugo Relearn Theme'
|
||||
weight = 1
|
||||
languageName = 'English'
|
||||
|
||||
[[languages.en.menu.shortcuts]]
|
||||
pre = '<i class="fa-fw fab fa-github"></i> '
|
||||
name = 'GitHub Repo'
|
||||
url = 'https://github.com/McShelby/hugo-theme-relearn'
|
||||
weight = 10
|
||||
|
||||
[[languages.en.menu.shortcuts]]
|
||||
name = 'Showcases'
|
||||
pageRef = '/showcase'
|
||||
weight = 20
|
||||
|
||||
[[languages.en.menu.shortcuts]]
|
||||
name = 'Credits'
|
||||
pageRef = '/more/credits'
|
||||
weight = 30
|
||||
|
||||
[[languages.en.menu.shortcuts]]
|
||||
pre = '<i class="fa-fw fas fa-tags"></i> '
|
||||
name = 'Tags'
|
||||
pageRef = '/tags'
|
||||
weight = 40
|
||||
|
||||
[[languages.en.menu.shortcuts]]
|
||||
pre = '<i class="fa-fw fas fa-layer-group"></i> '
|
||||
name = 'Categories'
|
||||
pageRef = '/categories'
|
||||
weight = 50
|
||||
|
||||
[languages.pir]
|
||||
title = 'Captain Hugo Relearrrn Theme'
|
||||
weight = 2
|
||||
languageName = 'Arrr! Pirrratish'
|
||||
|
||||
[[languages.pir.menu.shortcuts]]
|
||||
name = '<i class="fa-fw fab fa-github"></i> GitHub Repo'
|
||||
identifier = 'ds'
|
||||
url = 'https://github.com/McShelby/hugo-theme-relearn'
|
||||
weight = 10
|
||||
|
||||
[[languages.pir.menu.shortcuts]]
|
||||
name = '<i class="fa-fw fas fa-camera"></i> Showcases'
|
||||
pageRef = '/showcase'
|
||||
weight = 11
|
||||
|
||||
[[languages.pir.menu.shortcuts]]
|
||||
pre = '<i class="fa-fw fab fa-github"></i> '
|
||||
name = 'GitHub Repo'
|
||||
url = 'https://github.com/McShelby/hugo-theme-relearn'
|
||||
weight = 10
|
||||
|
||||
[[languages.pir.menu.shortcuts]]
|
||||
name = 'Showcases'
|
||||
pageRef = '/showcase'
|
||||
weight = 20
|
||||
|
||||
[[languages.pir.menu.shortcuts]]
|
||||
name = 'Crrredits'
|
||||
pageRef = '/more/credits'
|
||||
weight = 30
|
||||
|
||||
[[languages.pir.menu.shortcuts]]
|
||||
pre = '<i class="fa-fw fas fa-tags"></i> '
|
||||
name = 'Arrr! Tags'
|
||||
pageRef = '/tags'
|
||||
weight = 40
|
||||
|
||||
[[languages.pir.menu.shortcuts]]
|
||||
pre = '<i class="fa-fw fas fa-layer-group"></i> '
|
||||
name = 'Categorrries'
|
||||
pageRef = '/categories'
|
||||
weight = 50
|
||||
{{< /multiconfig >}}
|
||||
|
||||
## Displaying Pages Only in the Shortcuts Menu
|
||||
|
||||
To show pages only in the shortcuts menu you have two choices
|
||||
|
||||
1. Create a [headless branch bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle), `_index.md` in its own folder with the below front matter. The branch bundle will **not** be contained in the sitemap.
|
||||
|
||||
{{< multiconfig fm=true file="content/showcase/_index.en.md" >}}
|
||||
title = 'Showcase'
|
||||
[_build]
|
||||
render = 'always'
|
||||
list = 'never'
|
||||
publishResources = true
|
||||
{{< /multiconfig >}}
|
||||
|
||||
2. Or, put a child page inside a headless branch bundle with the following front matter in the bundle. This causes the child but not the branch bundle to be contained in the sitemap.
|
||||
|
||||
{{< multiconfig fm=true file="content/more/_index.en.md" >}}
|
||||
[_build]
|
||||
render = 'never'
|
||||
list = 'never'
|
||||
publishResources = false
|
||||
{{< /multiconfig >}}
|
||||
|
||||
The child page can be any type of content.
|
||||
|
||||
{{< multiconfig fm=true file="content/more/credits_index.en.md" >}}
|
||||
title = 'Credits'
|
||||
{{< /multiconfig >}}
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
+++
|
||||
categories = ["howto"]
|
||||
description = "Add additional shortcut links to the sidebar"
|
||||
options = ["disableShortcutsTitle"]
|
||||
title = "Shortcut Menu"
|
||||
weight = 4
|
||||
+++
|
||||
{{< piratify >}}
|
||||
|
|
@ -24,7 +24,7 @@ weight = -0
|
|||
|
||||
### New
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can define the expansion state of your menus in the front matter. Please see further [documentation](authoring/frontmatter/menu#expand-state-of-submenus) for possible values and default behavior.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can define the expansion state of your menus in the front matter. Please see further [documentation](configuration/sidebar/menus#expand-state-of-submenus) for possible values and default behavior.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} New partials for defining pre/post content for menu items and the content. See [documentation](configuration/customization/partials) for further reading.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ weight = -4
|
|||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Hidden pages are displayed by default in their according tags page. You can now turn off this behavior by setting `disableTagHiddenPages=true` in your `hugo.toml`.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can define the expansion state of your menus for the whole site by setting the `alwaysopen` option in your `hugo.toml`. Please see further [documentation](authoring/frontmatter/menu#expand-state-of-submenus) for possible values and default behavior.
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can define the expansion state of your menus for the whole site by setting the `alwaysopen` option in your `hugo.toml`. Please see further [documentation](configuration/sidebar/menus#expand-state-of-submenus) for possible values and default behavior.
|
||||
|
||||
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} New front matter `ordersectionsby` option to change immediate children sorting in menu and `children` shortcode. Possible values are `title` or `weight`.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,9 +16,9 @@ weight = -22
|
|||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} You can now have structural sections in the hierarchical menu without generating a page for it.
|
||||
|
||||
This can come in handy, if content for such a section page doesn't make much sense to you. See [the documentation](authoring/frontmatter/menu#disable-menu-entries) for how to do this.
|
||||
This can come in handy, if content for such a section page doesn't make much sense to you. See [the documentation](configuration/sidebar/menus#disable-menu-entries) for how to do this.
|
||||
|
||||
This feature may require you to make changes to your existing installation if you are already using _[shortcuts to pages inside of your project](configuration/sidebar/shortcutmenu#displaying-pages-only-in-the-shortcuts-menu)_ with a _headless branch parent_.
|
||||
This feature may require you to make changes to your existing installation if you are already using _[shortcuts to pages inside of your project](configuration/sidebar/menus#displaying-pages-exclusively-in-a-hugo-menu)_ with a _headless branch parent_.
|
||||
|
||||
In this case it is advised to remove the `title` from the headless branch parent's front matter, as it will otherwise appear in your breadcrumbs.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ weight = -9
|
|||
|
||||
It was later discovered, that this causes pages only meant to be displayed in the `More` section of the menu and stored directly inside your `content` directory to now show up in the menu as well.
|
||||
|
||||
To [get rid](configuration/sidebar/shortcutmenu#displaying-pages-only-in-the-shortcuts-menu) of this undesired behavior you have two choices:
|
||||
To [get rid](configuration/sidebar/menus#displaying-pages-exclusively-in-a-hugo-menu) of this undesired behavior you have two choices:
|
||||
|
||||
1. Make the page file a [headless branch bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle) (contained in its own subdirectory and called `_index.md`) and add the following front matter configuration to the file (see exampleSite's `content/showcase/_index.en.md`). This causes its content to **not** be ontained in the sitemap.
|
||||
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ weight = -0
|
|||
- suffered from poor build performance for sites with 1000 or more pages
|
||||
- reinvented the wheel instead of using available Hugo mechanisms
|
||||
|
||||
_What do I gain_, you may ask. A significant performance boost during build! Usually, the build time has been cut at least in half for bigger sites. It is now possible to build even larger sites with 5000 or more pages. This was previously almost impossible due to rapidly increasing build time with the more pages you've introduced. For even bigger sites, the theme now has [configurable performance optimizations](authoring/frontmatter/menu#expander-for-submenus) - at the price of feature limitations.
|
||||
_What do I gain_, you may ask. A significant performance boost during build! Usually, the build time has been cut at least in half for bigger sites. It is now possible to build even larger sites with 5000 or more pages. This was previously almost impossible due to rapidly increasing build time with the more pages you've introduced. For even bigger sites, the theme now has [configurable performance optimizations](configuration/sidebar/menus#expander-for-submenus) - at the price of feature limitations.
|
||||
|
||||
If you haven't done customizations to any partials, you can update right away.
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ weight = -0
|
|||
Also, a lot of previously undocumented features are now included, namely
|
||||
|
||||
- the [hidden pages](configuration/content/hidden) feature
|
||||
- options of the [navigation menu](authoring/frontmatter/menu)
|
||||
- [options of the menus](configuration/sidebar/menus)
|
||||
- configuring [breadcrumb, titles](configuration/content/titles) and [headings](configuration/content/headings) of your content
|
||||
- [options for using links](configuration/content/linking)
|
||||
- adding [custom output formats](configuration/customization/outputformats)
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ weight = -1
|
|||
|
||||
### Change
|
||||
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The sidebar menus are now [completely configurable](authoring/frontmatter/menu).
|
||||
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The sidebar menus are now [completely configurable](configuration/sidebar/menus).
|
||||
|
||||
This is provided by the new parameter `sidebarmenus`. With the new system, you can
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
7.0.1+4ed15c8096764c75a97ef858bb3a4c0d784fe888
|
||||
7.0.1+41904794583e7919627083c953a2b214ee59cd36
|
||||
Loading…
Reference in a new issue