docs: chapter 3 rough draft #567

README.md

@@ -31,7 +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/appearance/topbar#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 navigation menu](https://mcshelby.github.io/hugo-theme-relearn/content/organization)
+  - [Nested navigation menu](https://mcshelby.github.io/hugo-theme-relearn/content/structure)
   - [Configurable menu shortcuts](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/shortcutmenu)
   - [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)

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

@@ -1,6 +1,6 @@
 +++
 alwaysopen = false
-description = "Change colors, logos and the general appearance of your site"
+description = "Change colors, logos and the overall appearance of your site"
 title = "Appearance"
 weight = 2
 +++

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

@@ -1,6 +1,6 @@
 +++
 alwaysopen = false
-description = "Change colors, logos and the general appearance of your site"
+description = "Change colors, logos and the overall appearance of your site"
 title = "Appearance"
 weight = 2
 +++

exampleSite/content/configuration/appearance/branding/_index.en.md

@@ -96,7 +96,7 @@ The `identifier` option is mandatory and equivalent to the string in the first e
 | name                  | see notes       | The name to be displayed in the variant selector. If not set, the identifier is used in a human readable form. |
 | auto                  | _<empty>_ | If set, the variant is treated as an [auto mode variant](#adjust-to-os-settings). It has the same behavior as the `themeVariantAuto` option. The first entry in the array is the color variant for light mode, the second for dark mode. Defining auto mode variants with the advanced options has the benefit that you can now have multiple auto mode variants instead of just one with the simple options. |
 
-#### Example Configuration of This Site
+#### Example Configuration
 
 {{< multiconfig file=hugo >}}
 [params]

exampleSite/content/configuration/customization/designs/index.en.md

@@ -1,30 +1,41 @@
 +++
-description = "Using and extending page designs"
+description = "Extending page designs"
 title = "Page Designs"
 weight = 5
 +++
 
-The Relearn theme offers several page designs: `home`, `chapter`, and `default`. These are available as [archetypes](content/layouts) for site authors.
+A page is displayed by exactly one page design. The Relearn theme offers the page designs `home`, `chapter`, and `default`.
 
-To use a design, set [Hugo's reserved `type` option](https://gohugo.io/content-management/front-matter/#type) in your page's front matter.
+A page design usually consists of
 
-This leverages Hugo's [content view feature](https://gohugo.io/templates/types/#content-view). Don't use the `type` option in your modifications for other functionality!
+- [an archetype file](https://gohugo.io/content-management/archetypes/): a template for creating new Markdown files with this design
+- [content view files](https://gohugo.io/templates/types/#content-view): represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type) and backed by matching partials
+- CSS styles
 
-All designs use the theme's framework from `themes/hugo-theme-learn/layouts/_default/baseof.html`, containing of the same topbar and sidebar but can change how content appears in the center of the page.
+If no `type` is set in your front matter, the page is treated as if `type='default'` was set.
 
-### Creating Your Own Page Designs
+> [!warning]
+> Don't use the `type` option in your modifications for other functionality!
+
+All shipped designs use the theme's framework from `themes/hugo-theme-learn/layouts/_default/baseof.html`, containing of the same topbar and sidebar but can change how content appears in the center of the page.
+
+## Using a Page Design
+
+Regardless of shipped or custom page design, you are [using them](content/designs) in the same way.
+
+## Creating a Page Designs
 
 To make a custom page design:
 
 1. Choose a name (for example, `mydesign`)
-2. Create a file at `layouts/mydesign/views/article.html`
+2. Create a content view file at `layouts/mydesign/views/article.html`
-3. Add this content
 
     ````html {title="layouts/mydesign/views/article.html"}
     <article class="mydesign">
       <header class="headline">
     {{ partial "content-header.html" . }}
       </header>
+    <div class="article-subheading">AWESOME</div>
     {{ partial "heading-pre.html" . }}{{ partial "heading.html" . }}{{ partial "heading-post.html" . }}
     {{ partial "article-content.html" . }}
       <footer class="footline">
@@ -33,7 +44,40 @@ To make a custom page design:
     </article>
     ````
 
-In this file, you can customize the page design as needed. Typically, you'll want to:
+    In this file, you can customize the page design as needed. Typically, you'll want to:
 
-- Set a `class` at the `article` element for custom CSS styles
+    - Set a `class` at the `article` element for custom CSS styles
-- Use `{{ partial "article-content.html" . }}` to show your page content
+    - Use `{{ partial "article-content.html" . }}` to show your page content
+
+3. Create an archetype file at `archetypes/mydesign.md` (optional)
+
+    ````html {title="archetypes/mydesign.md"}
+    +++
+    title = "{{ replace .Name "-" " " | title }}"
+    type = "mydesign"
+    +++
+
+    This is my new design.
+    ````
+
+4. Add CSS in file `layouts/partials/custom-header.html` (optional)
+
+    ````html {title="layouts/partials/custom-header.html"}
+    <style>
+    .mydesign .article-subheading {
+      font-size: 72rem;
+    }
+    .mydesign a {
+      background-color: pink;
+    }
+    </style>
+    ````
+
+### Partials
+
+The above example uses `layouts/mydesign/views/article.html` but you have some others
+
+- `layouts/mydesign/baseof.html`: Completely redefine the whole HTML structure, none of the other listed partials will be used
+- `layouts/mydesign/views/menu.html`: Defines the sidebar menu layout
+- `layouts/mydesign/views/body.html`: Determines what to contain in the content area (for example a single page, a list of pages, a tree of sub pages)
+- `layouts/mydesign/views/article.html`: Controls how one page's content and title are displayed

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

@@ -7,10 +7,12 @@ weight = 3
 
 This page shows you, how to configure custom [image effects](content/markdown#image-effects) on top of existing ones.
 
-For a detailed usage example, see [this page](content/imageeffects).
+This setting can also be overridden by your front matter. For a detailed usage example, see [this page](content/imageeffects).
 
 If you don't configure anything in your `hugo.toml`, the image effects default to
 
+## Default Values
+
 {{< multiconfig >}}
 [imageEffects]
   border = false
@@ -19,37 +21,20 @@ If you don't configure anything in your `hugo.toml`, the image effects default t
   shadow = false
 {{< /multiconfig >}}
 
-{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can change these settings in your `hugo.toml`
+## Configuration
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can change these settings in your `hugo.toml` and add arbitrary custom effects as boolean values (like `bg-white` in the below snippet).
 
 {{< multiconfig file=hugo >}}
 [params]
   [params.imageEffects]
+    bg-white = true
     border = true
     lazy = false
 {{< /multiconfig >}}
 
 This would result in
 
-{{< multiconfig >}}
-[imageEffects]
-  border = true
-  lazy = false
-  lightbox = true
-  shadow = false
-{{< /multiconfig >}}
-
-## Adding Custom Effects
-
-You can add new effects with boolean values
-
-{{< multiconfig file=hugo >}}
-[params]
-  [params.imageEffects]
-    bg-white = true
-{{< /multiconfig >}}
-
-Result:
-
 {{< multiconfig >}}
 [imageEffects]
   bg-white = true
@@ -59,28 +44,30 @@ Result:
   shadow = false
 {{< /multiconfig >}}
 
-## Styling Custom Effects
-
-If the effective image effect value is
-
-- `true`: add a class with the effect's name
-- `false`: add a class with the effect's name and a "no" prefix
-
 ### Example
 
+With this configuration in effect, the following URL
+
 ````markdown {title="Markdown"}
 ![Minion](https://octodex.github.com/images/minion.png)
 ````
 
-### Result
+would result in
 
 ````html {title="HTML"}
 <img src="https://octodex.github.com/images/minion.png" loading="lazy" alt="Minion" class="bg-white border nolazy lightbox noshadow">
 ````
 
-Styles for default image effets are contained in the theme. Add custom styles for your extension image effects to `layouts/partials/content-header.html`.
+## Styling Effects
 
-In the above example you could add styles for both cases:
+If the resulting effect value is
+
+- `true`: add a class with the effect's name
+- `false`: add a class with the effect's name and a "no" prefix
+
+Styles for default effects are contained in the theme. Add styles for your custom effects to `layouts/partials/content-header.html`.
+
+For the above example you could add styles for both boolean cases:
 
 ````html {title="layouts/partials/content-header.html"}
 <style>

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

@@ -1,6 +1,6 @@
 +++
 alwaysopen = false
-description = "Configure the sidebar"
+description = "Configure all things sidebar"
 title = "Sidebar"
 weight = 3
 +++

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

@@ -1,6 +1,6 @@
 +++
 alwaysopen = false
-description = "Configure the sidebar"
+description = "Configure all things sidebar"
 title = "Sidebar"
 weight = 3
 +++

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

@@ -1,5 +1,5 @@
 +++
-description = "Configure the header and footer of the sidebar"
+description = "Configure the header and footer"
 options = ["disableLandingPageButton", "landingPageName", "showVisitedLinks"]
 title = "Header & Footer"
 weight = 2

exampleSite/content/configuration/sidebar/headerfooter/_index.pir.md

@@ -1,5 +1,5 @@
 +++
-description = "Configure the header and footer of the sidebar"
+description = "Configure the header and footer"
 options = ["disableLandingPageButton", "landingPageName", "showVisitedLinks"]
 title = "Header & Footer"
 weight = 2

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

@@ -5,7 +5,7 @@ title = "Navigation Menu"
 weight = 4
 +++
 
-The navigation menu is automatically created from [your content files](content/organization).
+The navigation menu is automatically created from [your content files](content/structure).
 
 All configurations options apply to all pages but can be changed in each page's front matter.
 
@@ -18,8 +18,7 @@ All configurations options apply to all pages but can be changed in each page's
   alwaysopen = true
 {{< /multiconfig >}}
 
-
+See the [user guide](content/navigationmenu#expand-state-of-nested-sections) how this setting will be applied.
-The current page's submenus are always expanded, regardless of this setting.
 
 ## Expander for Nested Sections
 

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

@@ -33,7 +33,7 @@ Edit `hugo.toml` and add `[[menu.shortcuts]]` entries for each link:
 
 {{< multiconfig file=hugo >}}
 [[menu.shortcuts]]
-  name = "<i class='fa-fw fab fa-github'></i> GitHub repo"
+  name = "<i class='fa-fw fab fa-github'></i> GitHub Repo"
   identifier = "ds"
   url = "https://github.com/McShelby/hugo-theme-relearn"
   weight = 10
@@ -72,7 +72,7 @@ For multilingual sites, set different menus for each language in `hugo.toml`:
     languageName = "English"
 
   [[languages.en.menu.shortcuts]]
-    name = "<i class='fa-fw fab fa-github'></i> GitHub repo"
+    name = "<i class='fa-fw fab fa-github'></i> GitHub Repo"
     identifier = "ds"
     url = "https://github.com/McShelby/hugo-theme-relearn"
     weight = 10
@@ -104,7 +104,7 @@ For multilingual sites, set different menus for each language in `hugo.toml`:
     languageName = "Arrr! Pirrratish"
 
   [[languages.pir.menu.shortcuts]]
-    name = "<i class='fa-fw fab fa-github'></i> GitHub repo"
+    name = "<i class='fa-fw fab fa-github'></i> GitHub Repo"
     identifier = "ds"
     url = "https://github.com/McShelby/hugo-theme-relearn"
     weight = 10

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

@@ -1,5 +1,5 @@
 +++
-description = "What site-wide meta nformation can be set"
+description = "What site-wide meta information can be set"
 frontmatter = ["description"]
 options = ["author.email", "author.name", "linkTitle"]
 title = "Meta Information"

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

@@ -1,5 +1,5 @@
 +++
-description = "What site-wide meta nformation can be set"
+description = "What site-wide meta information can be set"
 frontmatter = ["description"]
 options = ["author.email", "author.name", "linkTitle"]
 title = "Meta Information"

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

@@ -1,6 +1,6 @@
 +++
 description = "Your site's directory structure"
-title = "Basic Structure"
+title = "Directory Structure"
 weight = 1
 +++
 
@@ -8,7 +8,7 @@ If you've followed the [Getting Started](introduction/quickstart) guide, your di
 
 ````plaintext
 ├── content
-│   ├── basics
+│   ├── introduction
 │   │   ├── first-content
 |   |   |   └── _index.md
 │   │   ├── second-content

exampleSite/content/configuration/sitemanagement/structure/_index.pir.md

@@ -1,6 +1,6 @@
 +++
 description = "Your site's directory structure"
-title = "Basic Structure"
+title = "Directory Structure"
 weight = 1
 +++
 {{< piratify >}}

exampleSite/content/content/designs/_index.en.md

@@ -0,0 +1,77 @@
++++
+description = "How to vary layouts by using page designs"
+title = "Page Designs"
+weight = 5
++++
+
+A page is displayed by exactly one page design and represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type).
+
+The Relearn theme offers the page designs `home`, `chapter`, and `default` but you can [define further custom page designs](configuration/customization/designs).
+
+Regardless of shipped or custom page design, you are using them in the same way.
+
+- If you have an [archetype file](https://gohugo.io/content-management/archetypes/), you can just do
+
+    ````shell
+	hugo new --kind chapter chapter1/_index.md
+    ````
+
+- If you are creating your Markdown files manually, you can achieve the same by just setting `type='chapter'` in the front matter.
+
+Your resulting Markdown file needs to have at least the `type` front matter set to the value of the page design
+
+````toml {title="_index.md"}
++++
+title = "Chapter 1"
+type = "chapter"
++++
+````
+
+
+## Predefined Designs
+
+### Home {#archetypes-home}
+
+A **Home** page is the starting page of your project. It's best to have only one page of this kind in your project.
+
+To create a home page, run the following command
+
+````shell
+hugo new --kind home _index.md
+````
+
+![Home page](pages-home.png?width=60pc)
+
+### Chapter {#archetypes-chapter}
+
+A **Chapter** displays a page meant to be used as introduction for a set of child pages.
+
+Commonly, it contains a title front matter and a short description in the content.
+
+To create a chapter page, run the following command
+
+````shell
+hugo new --kind chapter chapter1/_index.md
+````
+
+If a numerical `weight` front matter is set, it will be used to generate the subtitle of the chapter page. Set the number to a consecutive value starting at 1 for each new chapter on the same directory level.
+
+![Chapter page](pages-chapter.png?width=60pc)
+
+### Default {#archetypes-default}
+
+A **Default** page is any other content page.
+
+To create a default page, run either one of the following commands
+
+````shell
+hugo new chapter1/page1/_index.md
+````
+
+or
+
+````shell
+hugo new chapter1/page1.md
+````
+
+![Default page](pages-default.png?width=60pc)

exampleSite/content/content/designs/_index.pir.md

@@ -0,0 +1,6 @@
++++
+description = "How to vary layouts by using page designs"
+title = "Page Designs"
+weight = 5
++++
+{{< piratify >}}

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

@@ -1,7 +1,8 @@
 +++
+description = "All front matter for the Relearn theme"
 tags = ["reference"]
 title = "Front Matter Reference"
-weight = 6
+weight = 8
 +++
 
 Every Hugo page must have front matter.
@@ -34,69 +35,3 @@ Here's a list of all available front matter with example values.  Default values
 +++
 {{% include "frontmatter.toml" %}}+++
 ````
-
-## Some Detailed Examples
-
-### Add Icon to a Menu Entry
-
-In the page front matter, add a `menuPre` param to insert any HTML code before the menu label. The example below uses the GitHub icon.
-
-{{< multiconfig fm=true >}}
-title = "GitHub repo"
-menuPre = "<i class='fab fa-github'></i> "
-{{< /multiconfig >}}
-
-![Title with icon](frontmatter-icon.png?width=18.75rem)
-
-### Ordering Sibling Menu/Page Entries
-
-Hugo provides a [flexible way](https://gohugo.io/content/ordering/) to handle order for your pages.
-
-The simplest way is to set `weight` parameter to a number.
-
-{{< multiconfig fm=true >}}
-title = "My page"
-weight = 5
-{{< /multiconfig >}}
-
-### Using a Custom Title for Menu Entries
-
-By default, the Relearn theme will use a page's `title` attribute for the menu item.
-
-But a page's title has to be descriptive on its own while the menu is a hierarchy. Hugo adds the `linkTitle` parameter for that purpose:
-
-For example (for a page named `content/install/linux.md`):
-
-{{< multiconfig fm=true >}}
-title = "Install on Linux"
-linkTitle = "Linux"
-{{< /multiconfig >}}
-
-### Override Expand State Rules for Menu Entries
-
-You can change how the theme expands menu entries on the side of the content with the `alwaysopen` setting on a per page basis. If `alwaysopen=false` for any given entry, its children will not be shown in the menu as long as it is not necessary for the sake of navigation.
-
-The theme generates the menu based on the following rules:
-
-- all parent entries of the active page including their siblings are shown regardless of any settings
-- immediate children entries of the active page are shown regardless of any settings
-- if not overridden, all other first level entries behave like they would have been given `alwaysopen=false`
-- if not overridden, all other entries of levels besides the first behave like they would have been given `alwaysopen=true`
-- all visible entries show their immediate children entries if `alwaysopen=true`; this proceeds recursively
-- all remaining entries are not shown
-
-You can see this feature in action on the example page for [children shortcode](shortcodes/children) and its children pages.
-
-## Disable Section Pages
-
-You may want to structure your pages in a hierarchical way but don't want to generate pages for those sections? The theme got you covered.
-
-To stay with the initial example: Suppose you want `level-one` appear in the sidebar but don't want to generate a page for it. So the entry in the sidebar should not be clickable but should show an expander.
-
-For this, open `content/level-one/_index.md` and add the following front matter
-
-{{< multiconfig fm=true >}}
-collapsibleMenu = true
-[_build]
-  render = "never"
-{{< /multiconfig >}}

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

@@ -1,6 +1,7 @@
 +++
+description = "All front matter for the Relearn theme"
 tags = ["reference"]
-title = "Frrront Matter Reference"
+title = "Front Matter Reference"
-weight = 6
+weight = 8
 +++
 {{< piratify >}}

exampleSite/content/content/frontmatter/frontmatter.toml

@@ -26,6 +26,12 @@ title = "Example Page"
 # twitter cards.
 description = ""
 
+# The page design to be used
+# Default: not set
+# This decides the layout of your page. The theme ships 'home', 'chapter' and
+# 'default'. If not set, 'default' is taken.
+type = ""
+
 ###############################################################################
 # Relearn Theme
 # These options are specific to the Relearn theme.

exampleSite/content/content/image/_index.pir.md

@@ -1,6 +0,0 @@
-+++
-description = "Featured Images for social media"
-title = "Featured Images"
-weight = 2
-+++
-{{< piratify >}}

exampleSite/content/content/imageeffects.en.md

@@ -1,12 +1,15 @@
 +++
-description = "How to extend image effects"
+description = "How to apply graphical effects to your images"
 frontmatter = ["imageEffects"]
-options = ["imageEffects"]
+title = "Image Effects"
-title = "Custom Image Effects"
+weight = 7
-weight = 3
 +++
 
-The theme supports non-standard [image effects](content/markdown#image-effects).
+The theme offers [graphical effects](content/markdown#image-effects) for your linked images.
+
+You can [define additional custom image effects](configuration/customization/imageeffects) in your configuration.
+
+The default image effects shipped with the theme are
 
 | Name     | Description                                                       |
 | -------- | ----------------------------------------------------------------- |
@@ -15,32 +18,33 @@ The theme supports non-standard [image effects](content/markdown#image-effects).
 | lightbox | The image will be clickable to show it enlarged                   |
 | shadow   | Draws a shadow around the image to make it appear hovered/glowing |
 
-As [described](content/markdown#image-effects), you can add this to the URL query parameter, but this may be cumbersome to be done consistently for the whole page. Instead, you can configure the defaults in your `hugo.toml` as well as overriding these default in the pages front matter.
+As [described](content/markdown#image-effects), one way to use them is to add them as URL query parameter.
 
-Explicitly set URL query parameter will override the defaults in effect for a page or your site.
+This can become cumbersome to be done consistently for the whole site. Instead, you can configure the defaults in your `hugo.toml` as well as overriding these defaults in a page's front matter.
+
+Explicitly set URL query parameter will override the defaults set for a page or your site.
 
 Without any settings in your `hugo.toml` `imageEffects` defaults to
 
-{{< multiconfig file=hugo >}}
+{{< multiconfig >}}
-[params]
+[imageEffects]
-  [params.imageEffects]
   border = false
   lazy = true
   lightbox = true
   shadow = false
 {{< /multiconfig >}}
 
-{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} This can be overridden in a pages front matter by eg.
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} This can be overridden in a pages front matter for example by
 
 {{< multiconfig fm=true >}}
 [imageEffects]
-  border = true
+  lazy = false
 {{< /multiconfig >}}
 
 Or by explicitly override settings by URL query parameter
 
 ````md {title="URL"}
-![Minion](https://octodex.github.com/images/minion.png?lightbox=false&bg-white=true)
+![Minion](https://octodex.github.com/images/minion.png?lazy=true&lightbox=false)
 ````
 
 The settings applied to the above image would be
@@ -50,30 +54,4 @@ border = true
 lazy = true
 lightbox = false
 shadow = false
-bg-white = true
 {{< /multiconfig >}}
-
-This ends up in the following HTML where the parameter are converted to CSS classes.
-
-````html {title="HTML"}
-<img src="https://octodex.github.com/images/minion.png?lightbox=false&bg-white=true" loading="lazy" alt="Minion" class="bg-white border lazy nolightbox noshadow">
-````
-
-
-## Extending
-
-{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} As you can see in the above example, the `bg-white` parameter is not initially supported in the themes default settings. The theme allows you to define arbitrary parameter by just adding them to the URL query parameter or set them in your page's front matter or `hugo.toml`.
-
-{{< multiconfig file=hugo >}}
-[params]
-  [params.imageEffects]
-    bg-white = true
-    border = false
-    lazy = true
-    lightbox = true
-    shadow = false
-{{< /multiconfig >}}
-
-{{% notice note %}}
-If no extended parameter like `bg-white` in the example is set on the URL, a `class="nobg-white"` in the HTML will only be generated if a default value was set in the page's front matter or `hugo.toml` .
-{{% /notice %}}

exampleSite/content/content/imageeffects.pir.md

@@ -1,6 +1,7 @@
 +++
-description = "How to extend image effects"
+description = "How to apply graphical effects to your images"
-title = "Custom Image Effects"
+frontmatter = ["imageEffects"]
-weight = 3
+title = "Image Effects"
+weight = 7
 +++
 {{< piratify >}}

exampleSite/content/content/layouts/_index.en.md

@@ -1,128 +0,0 @@
-+++
-title = "Layouts"
-weight = 2
-+++
-
-Using the command: `hugo new [relative new content path]`, you can start a content file with the date and title automatically set. While this is a welcome feature, active writers need more: [archetypes](https://gohugo.io/content/layouts/). These are preconfigured skeleton pages with default front matter.
-
-The Relearn theme defines some few archetypes of pages but you are free to define new ones to your liking. All can be used at any level of the documentation, the only difference being the layout of the content.
-
-## Predefined Archetypes
-
-### Home {#archetypes-home}
-
-A **Home** page is the starting page of your project. It's best to have only one page of this kind in your project.
-
-![Home page](pages-home.png?width=60pc)
-
-To create a home page, run the following command
-
-````shell
-hugo new --kind home _index.md
-````
-
-This leads to a file with the following content
-
-````toml {title="_index.md"}
-+++
-title = "{{ replace .Name "-" " " | title }}"
-type = "home"
-+++
-
-Lorem Ipsum.
-````
-
-### Chapter {#archetypes-chapter}
-
-A **Chapter** displays a page meant to be used as introduction for a set of child pages. Commonly, it contains a simple title and a catch line to define content that can be found below it.
-
-![Chapter page](pages-chapter.png?width=60pc)
-
-To create a chapter page, run the following command
-
-````shell
-hugo new --kind chapter <name>/_index.md
-````
-
-This leads to a file with the following content
-
-````toml {title="_index.md"}
-+++
-title = "{{ replace .Name "-" " " | title }}"
-type = "chapter"
-weight = 1
-+++
-
-Lorem Ipsum.
-````
-
-The `weight` number will be used to generate the subtitle of the chapter page, set the number to a consecutive value starting at 1 for each new chapter level.
-
-### Default {#archetypes-default}
-
-A **Default** page is any other content page. If you set an unknown archetype in your front matter, this archetype will be used to generate the page.
-
-![Default page](pages-default.png?width=60pc)
-
-To create a default page, run either one of the following commands
-
-````shell
-hugo new <chapter>/<name>/_index.md
-````
-
-or
-
-````shell
-hugo new <chapter>/<name>.md
-````
-
-This leads to a file with the following content
-
-````toml {title="*.md"}
-+++
-title = "{{ replace .Name "-" " " | title }}"
-+++
-
-Lorem Ipsum.
-````
-
-## Self defined Archetypes
-
-If you are in need of further archetypes you can define your own or even redefine existing ones.
-
-### Template
-
-Define a template file in your project at `archetypes/<kind>.md` and make sure it has at least the front matter parameter for that archetype like
-
-````toml {title="&lt;kind&gt;.md"}
-+++
-type = "<kind>"
-+++
-````
-
-Afterwards you can generate new content files of that kind with the following command
-
-````shell
-hugo new --kind <kind> <name>/_index.md
-````
-
-### Partials
-
-To define how your archetypes are rendered, define corresponding partial files in your projects directory `layouts/partials/archetypes/<kind>`.
-
-If you use an unknown archetype in your front matter, the `default` archetype will be used to generate the page.
-
-Related to each archetype, several _hook_ partial files in the form of `<hook>.html` can be given inside each archetype directory. If a partial for a specific hook is missing, no output is generated for this hook.
-
-The following hooks are used:
-
-| Name                 | Notes       |
-|----------------------|-------------|
-| styleclass           | Defines a set of CSS classes to be added to the HTML's `<main>` element. You can use these classes to define own CSS rules in your `custom-header.html` |
-| article              | Defines the HTML how to render your content |
-
-Take a look at the existing archetypes of this theme to get an idea how to utilize it.
-
-#### Output formats
-
-Each hook file can be overridden of a specific [output format](https://gohugo.io/templates/output-formats/). Eg. if you define a new output format `PLAINTEXT` in your `hugo.toml`, you can add a file `layouts/partials/archetypes/default.plaintext.html` to change the way how normal content is written for that output format.

exampleSite/content/content/layouts/_index.pir.md

@@ -1,5 +0,0 @@
-+++
-title = "Layouts"
-weight = 2
-+++
-{{< piratify >}}

exampleSite/content/content/markdown.en.md

@@ -1,7 +1,8 @@
 +++
-tags = ["Content"]
+description = "Reference of Commonmark and Markdown extensions"
+tags = ["reference"]
 title = "Markdown Syntax"
-weight = 3
+weight = 6
 +++
 
 Let's face it: Writing content for the web is tiresome. WYSIWYG editors help alleviate this task, but they generally result in horrible code, or worse yet, ugly web pages.

exampleSite/content/content/markdown.pir.md

@@ -1,6 +1,7 @@
 +++
-tags = ["Content"]
+description = "Reference of Commonmark and Markdown extensions"
+tags = ["reference"]
 title = "Marrrkdown Rules"
-weight = 3
+weight = 6
 +++
 {{< piratify >}}

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

@@ -1,6 +1,6 @@
 +++
-description = "Featured Images for social media"
+description = "What page meta information can be set"
-title = "Featured Images"
+title = "Meta Information"
 weight = 2
 +++
 

exampleSite/content/content/meta/_index.pir.md

@@ -0,0 +1,6 @@
++++
+description = "What page meta information can be set"
+title = "Meta Information"
+weight = 2
++++
+{{< piratify >}}

exampleSite/content/content/navigationmenu/_index.en.md

@@ -0,0 +1,81 @@
++++
+description = "Per page behavior of the navigation menu"
+title = "Navigation Menu"
+weight = 4
++++
+
+## Custom Title for Menu Entries
+
+By default, the Relearn theme will use a page's `title` front matter for the menu entry.
+
+But a page's title has to be descriptive on its own while the menu is a hierarchy. Use `linkTitle` to shorten the text of the menu entry.
+
+For example (for a page named `content/install/linux.md`):
+
+{{< multiconfig fm=true >}}
+title = "Install on Linux"
+linkTitle = "Linux"
+{{< /multiconfig >}}
+
+## Add Icon to a Menu Entry
+
+In the page front matter, add a `menuPre` to insert any HTML code before the menu label. You can also set `menuPost` to insert HTML code after the menu label.
+
+The example below uses the GitHub icon.
+
+{{< multiconfig fm=true >}}
+title = "GitHub Repo"
+menuPre = "<i class='fab fa-github'></i> "
+{{< /multiconfig >}}
+
+![Title with icon](frontmatter-icon.png?width=18.75rem)
+
+## Ordering Sibling Menu Entries
+
+### By Weight
+
+Hugo provides a [simple way](https://gohugo.io/getting-started/glossary/#weight) to handle order for your pages by setting the `weight` front matter to a number.
+
+{{< multiconfig fm=true >}}
+title = "My page"
+weight = 5
+{{< /multiconfig >}}
+
+### Other
+
+Using the `weight` for sorting can get cumbersome if you, for example, just want to sort alphabetically. Each time you add a new page in the set of pages, you may have to renumber some or all of them to make space for the new page.
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Use `ordersectionsby` to choose how navigation menus are sorted. The default is `weight`. You can sort by `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length`, or `default` (Hugo's standard order).
+
+{{< multiconfig fm=true >}}
+ordersectionsby = 'linktitle'
+{{< /multiconfig >}}
+
+## Expand State of Nested Sections
+
+You can change how the theme submenus appear with `alwaysopen` on a per page basis. If `alwaysopen=false` for any given entry, its children will not be shown in the menu as long as it is not necessary for the sake of navigation.
+
+The theme generates the menu based on the following rules:
+
+- all parent entries of the active page including their visible siblings are shown regardless of any settings
+- immediate child entries of the active page are shown regardless of any settings
+- if not overridden, all other first level entries behave like they would have been given `alwaysopen=false`
+- if not overridden, all other entries of levels besides the first behave like they would have been given `alwaysopen=true`
+- all visible entries show their immediate child entries if `alwaysopen=true`; this proceeds recursively
+- all remaining entries are not shown
+
+You can see this feature in action on the example page for [children shortcode](shortcodes/children) and its child pages.
+
+## Disable Section Pages
+
+You may want to structure your pages in a hierarchical way but don't want to generate pages for those sections? The theme got you covered.
+
+To stay with the [initial example](content/structure): Suppose you want `introduction/first-content` appear in the sidebar but don't want to generate a page for it. So the entry in the sidebar should not be clickable but should show an expander.
+
+For this, open `content/introduction/first-content/_index.md` and add the following front matter
+
+{{< multiconfig fm=true >}}
+collapsibleMenu = true
+[_build]
+  render = "never"
+{{< /multiconfig >}}

exampleSite/content/content/navigationmenu/_index.pir.md

@@ -0,0 +1,6 @@
++++
+tags = ["reference"]
+title = "Navigation Menu"
+weight = 4
++++
+{{< piratify >}}

exampleSite/content/content/organization/index.en.md

@@ -1,52 +0,0 @@
-+++
-title = "Page Organization"
-weight = 1
-+++
-
-In **Hugo**, pages are the core of your site. Once it is configured, pages are definitely the added value to your documentation site.
-
-## Directories
-
-Organize your site like [any other Hugo project](https://gohugo.io/content/organization/). Typically, you will have a _content_ directory with all your pages.
-
-````plaintext
-content
-├── level-one
-│   ├── level-two
-│   │   ├── level-three
-│   │   │   ├── level-four
-│   │   │   │   ├── _index.md       <-- /level-one/level-two/level-three/level-four
-│   │   │   │   ├── page-4-a.md     <-- /level-one/level-two/level-three/level-four/page-4-a
-│   │   │   │   ├── page-4-b.md     <-- /level-one/level-two/level-three/level-four/page-4-b
-│   │   │   │   └── page-4-c.md     <-- /level-one/level-two/level-three/level-four/page-4-c
-│   │   │   ├── _index.md           <-- /level-one/level-two/level-three
-│   │   │   ├── page-3-a.md         <-- /level-one/level-two/level-three/page-3-a
-│   │   │   ├── page-3-b.md         <-- /level-one/level-two/level-three/page-3-b
-│   │   │   └── page-3-c.md         <-- /level-one/level-two/level-three/page-3-c
-│   │   ├── _index.md               <-- /level-one/level-two
-│   │   ├── page-2-a.md             <-- /level-one/level-two/page-2-a
-│   │   ├── page-2-b.md             <-- /level-one/level-two/page-2-b
-│   │   └── page-2-c.md             <-- /level-one/level-two/page-2-c
-│   ├── _index.md                   <-- /level-one
-│   ├── page-1-a.md                 <-- /level-one/page-1-a
-│   ├── page-1-b.md                 <-- /level-one/page-1-b
-│   └── page-1-c.md                 <-- /level-one/page-1-c
-├── _index.md                       <-- /
-└── page-top.md                     <-- /page-top
-````
-
-{{% notice note %}}
-`_index.md` is required in each directory, it's your "directory's home page"
-{{% /notice %}}
-
-## Create your project
-
-The following steps are here to help you initialize your new website. If you don't know Hugo at all, we strongly suggest you to train by following [great documentation for beginners](https://gohugo.io/overview/quickstart/).
-
-Hugo provides a `new` command to create a new website.
-
-````shell
-hugo new site <new_project>
-````
-
-The Relearn theme provides [archetypes](content/layouts) to help you create this kind of pages.

exampleSite/content/content/organization/index.pir.md

@@ -1,5 +0,0 @@
-+++
-title = "Plank Orrrganizat'n"
-weight = 1
-+++
-{{< piratify >}}

exampleSite/content/content/structure/index.en.md

@@ -0,0 +1,33 @@
++++
+description = "Your content's directory structure"
+title = "Directory Structure"
+weight = 1
++++
+
+In **Hugo**, pages are the core of your site.
+
+The theme generates the navigation menu out of the given directory structure.
+
+Organize your site like [any other Hugo project](https://gohugo.io/content/structure/). Typically, you will have a _content_ directory with all your pages.
+
+````plaintext
+content
+├── introduction
+│   ├── first-content
+|   |   |── _index.md
+|   │   ├── sub-content
+|   |   |   |── _index.md
+|   |   |   |── picture1.png
+|   |   |   └── plain.txt
+│   ├── second-content
+|   |   |── index.md
+|   |   |── picture1.png
+|   |   └── picture2.png
+│   └── third-content.md
+└── _index.md
+````
+
+> [!note]
+> While you can also go different, `_index.md` (with an underscore) is recommended for each directory, it's your _directory's home page_.
+>
+> See [Hugo's guide for content ](https://gohugo.io/content-management/) to learn more.

exampleSite/content/content/structure/index.pir.md

@@ -0,0 +1,6 @@
++++
+description = "Your content's directory structure"
+title = "Directory Structure"
+weight = 1
++++
+{{< piratify >}}

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](content/frontmatter#override-expand-state-rules-for-menu-entries) 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](content/navigationmenu#expand-state-of-nested-sections) 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.
 

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](content/frontmatter#override-expand-state-rules-for-menu-entries) 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](content/navigationmenu#expand-state-of-nested-sections) 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`.
 

exampleSite/content/introduction/releasenotes/5/0.en.md

@@ -18,7 +18,7 @@ weight = -0
 
 ### Change
 
-- {{% badge style="note" title=" " %}}Change{{% /badge %}} The way [archetypes](content/layouts) are used to generate output has changed. The new systems allows you, to redefine existing archetypes or even generate your own ones.
+- {{% badge style="note" title=" " %}}Change{{% /badge %}} The way [archetypes](content/designs) are used to generate output has changed. The new systems allows you, to redefine existing archetypes or even generate your own ones.
 
   Your existing markdown files will still work like before and therefore you don't need to change anything after the upgrade. Nevertheless, it is recommended to adapt your existing markdown files to the new way as follows:
 

exampleSite/content/introduction/releasenotes/5/22.en.md

@@ -16,7 +16,7 @@ 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](content/frontmatter#disable-section-pages) 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](content/navigationmenu#disable-section-pages) 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_.
 

exampleSite/content/introduction/releasenotes/5/23.en.md

@@ -36,7 +36,7 @@ weight = -23
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to adjust the menu width for your whole site. [See the docs](configuration/sidebar/width).
 
-- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release adds social media meta tags for the Open Graph protocol and Twitter Cards to your site. [See the docs](content/image).
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release adds social media meta tags for the Open Graph protocol and Twitter Cards to your site. [See the docs](content/meta).
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release comes with additional sort options for the menu and the [`children` shortcode](shortcodes/children). Both will now accept the following values: `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length` or `default` (adhering to Hugo's default sort order).
 

exampleSite/content/shortcodes/math.en.md

@@ -73,8 +73,6 @@ You can overwrite the settings by providing a JSON object in `mathJaxInitialize`
 
 Keep in mind that initialization settings of your pages front matter overwrite all settings of your configuration options.
 
-#### Example
-
 {{< multiconfig file=hugo >}}
 [params]
 mathJaxInitialize = "{ \"chtml\": { \"displayAlign\": \"left\" }, { \"tex\": { \"inlineMath\": [[\"\\(\", \"\\)\"], [\"@\", \"@\"]], displayMath: [[\"\\[\", \"\\]\"], [\"@@\", \"@@\"]] }, \"options\": { \"enableMenu\": false }"
@@ -86,8 +84,6 @@ mathJaxInitialize = "{ \"chtml\": { \"displayAlign\": \"left\" }, { \"tex\": { \
 
 In case you want do use a different version of the MathJax library but don't want to override the shipped version, you can set `customMathJaxURL` to the URL of the external MathJax library.
 
-#### Example
-
 {{< multiconfig file=hugo >}}
 [params]
 customMathJaxURL = "https://unpkg.com/mathjax/es5/tex-mml-chtml.js"

exampleSite/content/shortcodes/mermaid.en.md

@@ -89,8 +89,6 @@ In addition, you can merge settings for each individual graph through [diagram d
 
 In case you want do use a different version of the Mermaid library but don't want to override the shipped version, you can set `customMermaidURL` to the URL of the external Mermaid library.
 
-#### Example
-
 {{< multiconfig file=hugo >}}
 [params]
 customMermaidURL = "https://unpkg.com/mermaid/dist/mermaid.min.js"

exampleSite/content/shortcodes/openapi/_index.en.md

@@ -56,8 +56,6 @@ Please note that this can not resolve files inside of your `static` directory. T
 
 In case you want do use a different version of the Swagger UI library but don't want to override the shipped version, you can set `customOpenapiURL` to the URL of the external Swagger UI library.
 
-#### Example
-
 {{< multiconfig file=hugo >}}
 [params]
 customOpenapiURL = "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"

layouts/chapter/views/article.html

@@ -3,7 +3,7 @@
   <header class="headline">
     {{- partial "content-header.html" . }}
   </header>
-{{ partial "heading-pre.html" . }}<div class="article-subheading">{{ T "Chapter" .Params.Weight }}</div>
+{{ partial "heading-pre.html" . }}{{ with .Params.Weight }}<div class="article-subheading">{{ T "Chapter" . }}</div>{{ end }}
 {{ partial "heading.html" . }}{{ partial "heading-post.html" . }}
 
 {{ partial "article-content.html" . }}

layouts/partials/version.txt

@@ -1 +1 @@
-6.4.0+c092b94fd80ed72dedbe7726881b98027cf76621
+6.4.0+557763f09a061c12835a34d1538f3fc33b2a546b