diff --git a/README.md b/README.md index a93e03c4c6..c7ad0d0830 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/exampleSite/content/authoring/frontmatter/menu/_index.pir.md b/exampleSite/content/authoring/frontmatter/menu/_index.pir.md deleted file mode 100644 index b70aa52303..0000000000 --- a/exampleSite/content/authoring/frontmatter/menu/_index.pir.md +++ /dev/null @@ -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 >}} \ No newline at end of file diff --git a/exampleSite/content/authoring/frontmatter/menus/_index.en.md b/exampleSite/content/authoring/frontmatter/menus/_index.en.md new file mode 100644 index 0000000000..96450e80c7 --- /dev/null +++ b/exampleSite/content/authoring/frontmatter/menus/_index.en.md @@ -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). diff --git a/exampleSite/content/authoring/frontmatter/menus/_index.pir.md b/exampleSite/content/authoring/frontmatter/menus/_index.pir.md new file mode 100644 index 0000000000..bcee333c36 --- /dev/null +++ b/exampleSite/content/authoring/frontmatter/menus/_index.pir.md @@ -0,0 +1,6 @@ ++++ +description = "Setting the behavior of the menus" +title = "Menus" +weight = 2 ++++ +{{< piratify >}} \ No newline at end of file diff --git a/exampleSite/content/authoring/frontmatter/menu/_index.en.md b/exampleSite/content/configuration/sidebar/menus/_index.en.md similarity index 82% rename from exampleSite/content/authoring/frontmatter/menu/_index.en.md rename to exampleSite/content/configuration/sidebar/menus/_index.en.md index 2ad15ebefc..1f0f4955ec 100644 --- a/exampleSite/content/authoring/frontmatter/menu/_index.en.md +++ b/exampleSite/content/configuration/sidebar/menus/_index.en.md @@ -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 >}} diff --git a/exampleSite/content/configuration/sidebar/menus/_index.pir.md b/exampleSite/content/configuration/sidebar/menus/_index.pir.md new file mode 100644 index 0000000000..5cd3896b90 --- /dev/null +++ b/exampleSite/content/configuration/sidebar/menus/_index.pir.md @@ -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 >}} \ No newline at end of file diff --git a/exampleSite/content/configuration/sidebar/shortcutmenu/_index.en.md b/exampleSite/content/configuration/sidebar/shortcutmenu/_index.en.md deleted file mode 100644 index 7819c1165b..0000000000 --- a/exampleSite/content/configuration/sidebar/shortcutmenu/_index.en.md +++ /dev/null @@ -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 = ' ' - 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 = ' ' - name = 'Tags' - pageRef = '/tags' - weight = 40 - -[[menu.shortcuts]] - pre = ' ' - 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 = ' ' - 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 = ' ' - name = 'Tags' - pageRef = '/tags' - weight = 40 - - [[languages.en.menu.shortcuts]] - pre = ' ' - name = 'Categories' - pageRef = '/categories' - weight = 50 - - [languages.pir] - title = 'Captain Hugo Relearrrn Theme' - weight = 2 - languageName = 'Arrr! Pirrratish' - - [[languages.pir.menu.shortcuts]] - name = ' GitHub Repo' - identifier = 'ds' - url = 'https://github.com/McShelby/hugo-theme-relearn' - weight = 10 - - [[languages.pir.menu.shortcuts]] - name = ' Showcases' - pageRef = '/showcase' - weight = 11 - - [[languages.pir.menu.shortcuts]] - pre = ' ' - 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 = ' ' - name = 'Arrr! Tags' - pageRef = '/tags' - weight = 40 - - [[languages.pir.menu.shortcuts]] - pre = ' ' - 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 >}} diff --git a/exampleSite/content/configuration/sidebar/shortcutmenu/_index.pir.md b/exampleSite/content/configuration/sidebar/shortcutmenu/_index.pir.md deleted file mode 100644 index 495d2d11c1..0000000000 --- a/exampleSite/content/configuration/sidebar/shortcutmenu/_index.pir.md +++ /dev/null @@ -1,8 +0,0 @@ -+++ -categories = ["howto"] -description = "Add additional shortcut links to the sidebar" -options = ["disableShortcutsTitle"] -title = "Shortcut Menu" -weight = 4 -+++ -{{< piratify >}} \ No newline at end of file diff --git a/exampleSite/content/introduction/releasenotes/2/0.en.md b/exampleSite/content/introduction/releasenotes/2/0.en.md index c85b36a380..231be9db25 100644 --- a/exampleSite/content/introduction/releasenotes/2/0.en.md +++ b/exampleSite/content/introduction/releasenotes/2/0.en.md @@ -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. diff --git a/exampleSite/content/introduction/releasenotes/2/4.en.md b/exampleSite/content/introduction/releasenotes/2/4.en.md index ef0c81b7ea..3997881ca8 100644 --- a/exampleSite/content/introduction/releasenotes/2/4.en.md +++ b/exampleSite/content/introduction/releasenotes/2/4.en.md @@ -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`. diff --git a/exampleSite/content/introduction/releasenotes/5/22.en.md b/exampleSite/content/introduction/releasenotes/5/22.en.md index e05f438297..10e2c7d66c 100644 --- a/exampleSite/content/introduction/releasenotes/5/22.en.md +++ b/exampleSite/content/introduction/releasenotes/5/22.en.md @@ -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. diff --git a/exampleSite/content/introduction/releasenotes/5/9.en.md b/exampleSite/content/introduction/releasenotes/5/9.en.md index 111f03284f..2dc7a3b23f 100644 --- a/exampleSite/content/introduction/releasenotes/5/9.en.md +++ b/exampleSite/content/introduction/releasenotes/5/9.en.md @@ -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. diff --git a/exampleSite/content/introduction/releasenotes/7/0.en.md b/exampleSite/content/introduction/releasenotes/7/0.en.md index 29f5534d52..7d508a9359 100644 --- a/exampleSite/content/introduction/releasenotes/7/0.en.md +++ b/exampleSite/content/introduction/releasenotes/7/0.en.md @@ -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) diff --git a/exampleSite/content/introduction/releasenotes/7/1.en.md b/exampleSite/content/introduction/releasenotes/7/1.en.md index dca4824db6..08abb5fd3e 100644 --- a/exampleSite/content/introduction/releasenotes/7/1.en.md +++ b/exampleSite/content/introduction/releasenotes/7/1.en.md @@ -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 diff --git a/layouts/partials/version.txt b/layouts/partials/version.txt index 4d8f58bf08..0566fbf518 100644 --- a/layouts/partials/version.txt +++ b/layouts/partials/version.txt @@ -1 +1 @@ -7.0.1+4ed15c8096764c75a97ef858bb3a4c0d784fe888 \ No newline at end of file +7.0.1+41904794583e7919627083c953a2b214ee59cd36 \ No newline at end of file