docs: honing #567

README.md

@@ -13,34 +13,34 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
 ## Key Features
 
 - **Versatile Usage**
-  - Responsive design for mobile devices
+  - [Responsive design for mobile devices](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/width)
-  - Looks nice on paper (if it has to)
+  - [Looks nice on paper - if it has to](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/outputformats)
   - Usable offline with no external dependencies
-  - [Usable from your local file system without a web server via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/deployment/)
+  - [Usable from your local file system without a web server via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/deployment)
   - Integration with the [VSCode Front Matter CMS extension](https://github.com/estruyf/vscode-front-matter) for on-premise CMS capabilities
 
 - **Customizable Appearance**
   - [Flexible brand image configuration](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#change-the-logo)
   - [Automatic light/dark mode switching based on OS settings](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#adjust-to-os-settings)
-  - Pre-defined color schemes and variants
+  - Pre-defined color variants
-  - [User-selectable theme variants](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#multiple-variants)
+  - [User-selectable variants](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding#multiple-variants)
   - [Built-in stylesheet generator](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/generator)
-  - [Customizable syntax highlighting](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/highlight)
+  - [Customizable syntax highlighting](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/branding/#change-syntax-highlighting)
 
 - **Advanced Functionality**
-  - [Chapter and site-wide printing capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/topbar/#print-support)
+  - [Chapter and site-wide printing capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/appearance/topbar#print-support)
-  - [Versatile search options: in-page, popup, and dedicated search page](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search/)
+  - [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/)
+  - [Customizable top bar buttons](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/topbar)
-  - [Unlimited nested menu structure](https://mcshelby.github.io/hugo-theme-relearn/content/organization)
+  - [Nested navigation menu](https://mcshelby.github.io/hugo-theme-relearn/content/organization)
-  - [Configurable menu shortcuts](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/shortcutmenu/)
+  - [Configurable menu shortcuts](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/shortcutmenu)
-  - Support for hidden pages
+  - [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/content/image/)
+  - [Social media integration](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/meta#social-media-images)
 
 - **Multilingual Support**
-  - [Full right-to-left (RTL) language support](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/multilingual/)
+  - [Full right-to-left (RTL) language support](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/multilingual)
   - [Extensive list of supported languages](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/multilingual): Arabic, Chinese (Simplified and Traditional), Czech, Dutch, English, Finnish, French, German, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Romanian, Russian, Spanish, Swahili, Turkish, Vietnamese
-  - [Multilingual content search capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search/#mixed-language-support)
+  - [Multilingual content search capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search#mixed-language-support)
 
 - **Enhanced Markdown Features**
   - [GitHub Flavored Markdown (GFM) support](https://mcshelby.github.io/hugo-theme-relearn/content/markdown)
@@ -49,15 +49,15 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
 
 - **Rich Shortcode Library**
   - [Customizable marker badges](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/badge)
-  - [Flexible button creation](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/button)
+  - [Flexible buttons](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/button)
   - [Child page listing](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/children)
   - [Expandable content areas](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/expand)
   - [Font Awesome icon integration](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/icon)
   - [File inclusion capabilities](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/include)
-  - [MathJax support for mathematical and chemical formulae](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/math)
+  - [Math support for mathematical and chemical formulae](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/math)
   - [Mermaid diagram integration](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/mermaid)
   - [Styled notice boxes](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/notice)
-  - [OpenAPI specification rendering with Swagger UI](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/openapi)
+  - [OpenAPI specification rendering](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/openapi)
   - [Page bundle resource display](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/resources)
   - [Site configuration parameter display](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/siteparam)
   - [Tab-based content organization](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/tab) and [multi-tab panels](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/tabs)

exampleSite/content/configuration/content/linking/index.en.md

@@ -7,7 +7,7 @@ weight = 4
 
 ## Opening Links
 
-By default, external links open in a new tab. To change this, use the `externalLinkTarget` setting with a proper [link target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, external links open in a new tab. To change this, use the `externalLinkTarget` setting with a proper [link target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
 
 For example, this will open links in the same tab
 
@@ -34,7 +34,7 @@ This option also comes for the [include](shortcodes/include#enabling-link-warnin
 
 ## Patching the `relref` Shortcode
 
-While the usage of `relref` is obsolete and discouraged by Hugo for a while, existing installations may still use it.
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} While the usage of `relref` is obsolete and discouraged by Hugo for a while, existing installations may still use it.
 
 In configurations using a baseURL **with** a subdirectory **and** having `relativeURLs=false` (the default) Hugo’s standard `relref` implementation was failing.
 

exampleSite/content/configuration/content/titles/index.en.md

@@ -5,12 +5,26 @@ title = "Titles & Breadcrumbs"
 weight = 2
 +++
 
+## Breadcrumbs
+
 {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `disableRootBreadcrumb=true` to remove the root breadcrumb which often feels redundant. This will also apply to the breadcrumbs of the search results and taxonomy pages.
 
-{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Further, you can override the breadcrumb separator by using `breadcrumbSeparator='/'`. This separator will also be used in the breadcrumbs of the search results and taxonomy pages.
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can override the default breadcrumb separator by using `breadcrumbSeparator='/'`. This separator will also be used in the breadcrumbs of the search results and taxonomy pages.
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default the term pages of a taxonomy will display the breadcrumb for each page. Set `disableTermBreadcrumbs=true` to remove the breadcrumb if the term pages look to cluttered.
 
 {{< multiconfig file=hugo >}}
 [params]
   disableRootBreadcrumb = true
   breadcrumbSeparator = '/'
+  disableTermBreadcrumbs = true
+{{< /multiconfig >}}
+
+## Titles
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can override the default title separator by using `titleSeparator='|'`.
+
+{{< multiconfig file=hugo >}}
+[params]
+  titleSeparator = '|'
 {{< /multiconfig >}}

exampleSite/content/configuration/customization/_index.en.md

@@ -1,6 +1,6 @@
 +++
 alwaysopen = false
-description = "Customize files for advanced customization"
+description = "Customize files for advanced usage"
 title = "Customization"
 weight = 5
 +++

exampleSite/content/configuration/customization/_index.pir.md

@@ -1,6 +1,6 @@
 +++
 alwaysopen = false
-description = "Customize files for advanced customization"
+description = "Customize files for advanced usage"
 title = "Customization"
 weight = 5
 +++

exampleSite/content/configuration/options/_index.en.md

@@ -1,5 +1,5 @@
 +++
-description = "Configuration options for the Relearn theme"
+description = "All configuration options for the Relearn theme"
 tags = ["reference"]
 title = "Options Reference"
 weight = 6

exampleSite/content/configuration/options/_index.pir.md

@@ -1,5 +1,5 @@
 +++
-description = "Configuration options for the Relearn theme"
+description = "All configuration options for the Relearn theme"
 tags = ["reference"]
 title = "Options Reference"
 weight = 6

exampleSite/content/configuration/sitemanagement/meta/_index.en.md

@@ -1,12 +1,14 @@
 +++
 description = "What site-wide meta nformation can be set"
+frontmatter = ["description"]
+options = ["author.email", "author.name"]
 title = "Meta Information"
 weight = 3
 +++
 
 ## Site Author Information
 
-The theme uses author details in various parts of your site, like RSS feeds and meta tags.
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} The theme uses author details in various parts of your site, like RSS feeds and meta tags.
 
 {{< multiconfig file=hugo >}}
 [params]
@@ -17,7 +19,7 @@ The theme uses author details in various parts of your site, like RSS feeds and
 
 ## Site Description
 
-The theme shows a site description in various places, such as RSS feeds and meta tags. For this, it uses the `description` field from your home page's front matter.
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} The theme shows a site description in various places, such as RSS feeds and meta tags. For this, it uses the `description` field from your home page's front matter.
 
 ## Social Media Images
 

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 (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/navigationmenu#expander-for-nested-sections) - at the price of feature limitations.
 
   If you haven't done customizations to any partials, you can update right away.
 
@@ -27,12 +27,10 @@ weight = -0
 
   Specifically, you will have to adapt your site if you have
 
-  - overwritten the `header.html`, `menu.html` or `footer.html` partials
+  - [overwritten the `header.html`, `menu.html` or `footer.html` partials](configuration/customization/partials)
-  - self-defined output formats that display HTML
+  - [self-defined output formats](configuration/customization/outputformats) that display HTML
-  - defined archetype partials in `layouts/partials/archetypes`
+  - defined archetype partials in `layouts/partials/archetypes` - now becoming [page designs](configuration/customization/designs)
-  - overwritten prev/next topbar buttons
+  - [overwritten prev/next topbar buttons](configuration/customization/topbar) - needs sync with the implementation changes
-
-  There is a separate section in the documentation covering these cases.
 
 - {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} This release changes the way the search index and the dedicated search page are generated. This may require reconfiguration by you to still work as you have intended.
 
@@ -79,11 +77,12 @@ weight = -0
 
   The docs now clearly differentiate between [configuration of your site](configuration), all things [writing page content](content) and the [shortcodes docs](shortcodes) that cover both topics, configuration and usage.
 
-  To give you a better overview of what's possible with the theme, we introduced reference pages for all theme [configuration options](configuration/options) and [front matter](content/frontmatter) and mark each occurrence of such on all pages with badges {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} and {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}}.
+  To give you a better overview of what's possible with the theme, we introduced reference pages for all theme [configuration options](configuration/options) and [front matter](content/frontmatter) and mark each occurrence of such on all pages with the badges {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} and {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}}.
 
   Also, a lot of previously undocumented features are now included, namely
 
   - the [hidden pages](configuration/content/hidden) feature
   - options of the [navigation menu](configuration/sidebar/navigationmenu)
-  - configuring the [headings](configuration/content/headings) of your content
+  - 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)

layouts/partials/version.txt

@@ -1 +1 @@
-6.4.0+fec603cbbd468c7be6ec978f9fc421b240a6e881
+6.4.0+d5d7a94e8f291cdd80d26ebda063f6a89fa50547

theme.toml

@@ -5,22 +5,25 @@ description = "A theme for Hugo designed for documentation"
 homepage = "https://github.com/McShelby/hugo-theme-relearn"
 demosite = "https://mcshelby.github.io/hugo-theme-relearn"
 tags = ["dark", "dark mode", "docs", "light", "multilingual", "responsive"]
-features = ["badges", "breadcrumbs", "boxes", "buttons",
+features = [
-  "categories", "chemical formulae", "customizable", "color variants",
+  "alerts",
+  "badges", "breadcrumbs", "boxes", "buttons",
+  "callouts", "categories", "chemical formulae", "customizable", "color variants",
   "dark", "dark mode", "docs", "documentation",
   "expand",
   "favicon", "file inclusion", "file system support", "font awesome", "front matter cms",
-  "gfm",
+  "gfm", "github flavored markdown",
   "hidden pages",
   "i18n", "icons", "image resizing", "include",
   "light", "lightbox", "logo",
   "math", "mathjax", "menu", "mermaid", "multilingual", "mobile",
-  "nested sections", "notice",
+  "nested menus", "nested sections", "notice",
   "oas", "offline usable", "openapi", "open graph",
   "print", "printable",
   "responsive", "rss", "rtl",
   "schema", "search", "search page", "sidebar", "sitemap", "subtheme", "swagger", "swaggerui", "syntax highlighting",
-  "table of contents", "tab", "tabs", "tags", "taxonomy", "themeable", "themes", "toc", "topbar buttons", "twitter cards"]
+  "table of contents", "tab", "tabs", "tags", "taxonomy", "themeable", "themes", "toc", "topbar buttons", "twitter cards"
+]
 
 [module]
   [module.hugoVersion]