docs: move exampleSite to docs #1003

docs/content/_index.en.md

@@ -0,0 +1,14 @@
++++
+description = "A theme for Hugo designed for documentation."
+title = "Hugo Relearn Theme"
+type = "home"
+[[cascade]]
+	[cascade._target]
+		path = "/introduction/changelog/*/*/*"
+	[cascade.params]
+		[cascade.params._build]
+			render = "never"
++++
+{{% replaceRE "https://mcshelby.github.io/hugo-theme-relearn/" "" %}}
+{{< include "README.md" "true" >}}
+{{% /replaceRE %}}

docs/content/_index.pir.md

@@ -0,0 +1,12 @@
++++
+description = "A theme fer Cap'n Hugo designed fer documentat'n."
+title = "Cap'n Hugo Relearrrn Theme"
+type = "home"
+[[cascade]]
+	[cascade._target]
+		path = "/introduction/changelog/*/*/*"
+	[cascade.params]
+		[cascade.params._build]
+			render = "never"
++++
+{{< piratify true >}}

docs/content/authoring/_index.en.md

@@ -0,0 +1,11 @@
++++
+categories = ["reference"]
+menuPre = "<i class='fa-fw fab fa-markdown'></i> "
+title = "Authoring"
+type = "chapter"
+weight = 3
++++
+
+Learn how to create and organize your content pages.
+
+{{% children containerstyle="div" style="h2" description=true %}}

docs/content/authoring/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["reference"]
+menuPre = "<i class='fa-fw fab fa-markdown'></i> "
+title = "Rambl'n"
+type = "chapter"
+weight = 3
++++
+{{< piratify >}}

docs/content/authoring/frontmatter/_index.en.md

@@ -0,0 +1,9 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "All things front matter"
+title = "Front Matter"
+weight = 2
++++
+
+{{% children containerstyle="div" style="h2" description=true %}}

docs/content/authoring/frontmatter/_index.pir.md

@@ -0,0 +1,8 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "All things front matter"
+title = "Front Matter"
+weight = 2
++++
+{{< piratify >}}

docs/content/authoring/frontmatter/designs/_index.en.md

@@ -0,0 +1,81 @@
++++
+categories = ["howto"]
+description = "How to vary layouts by using page designs"
+title = "Page Designs"
+weight = 1
++++
+
+Page designs are used to provide different layouts for your pages.
+
+A page is displayed by exactly one page design and is represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type).
+
+The Relearn theme ships with the page designs `home`, `chapter`, and `default` for the HTML output format but you can [define further custom page designs](configuration/customization/designs).
+
+## Using a Page Design
+
+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 to make your page displayed with the `chapter` page design.
+
+    ````toml {title="_index.md"}
+    +++
+    title = "Chapter 1"
+    type = "chapter"
+    +++
+    ````
+
+If no `type` is set in your front matter or the page design doesn't exist for a given output format, the page is treated as if `type='default'` was set.
+
+## Predefined Designs for the HTML Output Format
+
+### 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)

docs/content/authoring/frontmatter/designs/_index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["howto"]
+description = "How to vary layouts by using page designs"
+title = "Page Designs"
+weight = 1
++++
+{{< piratify >}}

docs/content/authoring/frontmatter/linking/index.en.md

@@ -0,0 +1,41 @@
++++
+categories = ["howto"]
+description = "What options are available for links and images"
+frontmatter = ["errorignore", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
+options = ["errorignore", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
+title = "Linking"
+weight = 3
++++
+
+## Opening Links
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /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
+
+{{< multiconfig >}}
+externalLinkTarget = '_self'
+{{< /multiconfig >}}
+
+## Enabling Link and Image Link Warnings
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can use `link.errorlevel` and `image.errorlevel` to control what should happen if a local link can not be resolved to a page and/or a resource.
+
+If not set or empty, any unresolved link is written as given into the resulting output. If set to `warning` the same happens and an additional warning is printed in the built console. If set to `error` an error message is printed and the build is aborted.
+
+Please note that this can not resolve files inside of your `static` directory. The file must be a resource of the page or the site.
+
+Link warnings are also available for the [include](shortcodes/include#enabling-link-warnings) and [openapi](shortcodes/openapi#enabling-link-warnings) shortcodes.
+
+{{< multiconfig >}}
+link.errorlevel = 'warning'
+image.errorlevel = 'warning'
+{{< /multiconfig >}}
+
+### Ignoring False Negatives
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} In case you want to use link warnings but are bothered by false negatives, you can configure an ignore list of regular expressions. The referenced address will be checked against all regexes of this list. If the address matches at least one regex, no output will be written to the console. The check uses [Hugo's `findRE` function](https://gohugo.io/functions/strings/findre/).
+
+{{< multiconfig >}}
+errorignore = [ '^/authoring/', '^/configuration/' ]
+{{< /multiconfig >}}

docs/content/authoring/frontmatter/linking/index.pir.md

@@ -0,0 +1,9 @@
++++
+categories = ["howto"]
+description = "What options are available for links and images"
+frontmatter = ["errorignore", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
+options = ["errorignore", "externalLinkTarget", "image.errorlevel", "link.errorlevel"]
+title = "Linking"
+weight = 3
++++
+{{< piratify >}}

docs/content/authoring/frontmatter/menus/_index.en.md

@@ -0,0 +1,6 @@
++++
+description = "Setting the behavior of the menus"
+title = "Menus"
+weight = 2
+menuPageRef = '/configuration/sidebar/menus'
++++

docs/content/authoring/frontmatter/menus/_index.pir.md

@@ -0,0 +1,6 @@
++++
+description = "Setting the behavior of the menus"
+title = "Menus"
+weight = 2
+menuPageRef = '/configuration/sidebar/menus'
++++

docs/content/authoring/frontmatter/reference/_index.en.md

@@ -0,0 +1,38 @@
++++
+categories = ["reference"]
+description = "All front matter for the Relearn theme"
+linkTitle = "Reference"
+title = "Front Matter Reference"
+weight = 5
++++
+
+Every Hugo page must have front matter.
+
+In addition to [Hugo's standard front matter](https://gohugo.io/content-management/front-matter/#fields), the Relearn theme offers extras settings listed here.
+
+Throughout the documentation, theme-specific front matter is marked with a {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} badge.
+
+Add theme front matter directly to the root of your page's front matter. For example:
+
+{{< multiconfig fm=true >}}
+  math = true
+{{< /multiconfig >}}
+
+## Index
+
+{{% taxonomy "frontmatter" "h3" %}}
+
+## All Front Matter
+
+Here's a list of all available front matter with example values.  Default values are described in the [annotated example](#annotated-front-matter) below or in each front matter's documentation.
+
+{{< multiconfig fm=true >}}
+{{% include "frontmatter.toml" %}}
+{{< /multiconfig >}}
+
+## Annotated Front Matter
+
+````toml {title="toml"}
++++
+{{% include "frontmatter.toml" %}}+++
+````

docs/content/authoring/frontmatter/reference/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["reference"]
+description = "All front matter for the Relearn theme"
+linkTitle = "Reference"
+title = "Front Matter Reference"
+weight = 5
++++
+{{< piratify >}}

docs/content/authoring/frontmatter/reference/frontmatter.toml

@@ -0,0 +1,408 @@
+# If an option value is said to be not set, you can achieve the same behavior
+# by giving it an empty string value.
+
+###############################################################################
+# Hugo
+# These options usually apply to other themes as well.
+
+# The social media image of your page.
+# Default: not set
+# This is used for generating social media meta information for the opengraph
+# protocol and twitter cards.
+# If not set, the set value of your site's hugo.toml is used.
+images = [ 'images/hero.png' ]
+
+# The title of your page.
+# Default: not set
+# A page without a title is treated as a hidden page.
+title = 'Example Page'
+
+# The description of your page.
+# Default: not set
+# This is used for generating HTML meta tags, social media meta information
+# for the opengraph protocol and twitter cards.
+# If not set, the set value of your site's hugo.toml is used for the html
+# meta tag, social media meta information for the opengraph protocol and
+# 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.
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# General
+# These options are defining general, non visual behavior.
+
+# Conditionally ignore errorlevel settings
+# Default: []
+# The theme supports checking referenced address (e.g. with
+# link.errorlevel, image.errorlevel, etc. see below). Sometimes checks lead
+# to console output due to false negatives. You can turn off the checks
+# for individual referenced addresses by defining regular expressions here.
+# The referenced address will be checked against all regexes of this array.
+# If it matches at least one, no output will be written to the console.
+# This array can be expanded globally in your site's hugo.toml.
+errorignore = []
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Topbar
+# These options modify the topbar appearance.
+
+# Hide the table of contents button.
+# Default: false
+# If the TOC button is hidden, also the keyboard shortcut is disabled.
+# If not set, the set value of your site's hugo.toml is used.
+disableToc = false
+
+# Hide the breadcrumbs.
+# Default: false
+# If the breadcrumbs are hidden, the title of the displayed page will still be
+# shown in the topbar.
+disableBreadcrumb = false
+
+# Hide the Markdown button.
+# Default: false
+# This hides the Markdown button if you activated the Markdown output format.
+# If not set, the set value of your site's hugo.toml is used.
+disableMarkdownButton = false
+
+# Hide the Source button.
+# Default: false
+# This hides the Source button if you activated the Source output format.
+# If not set, the set value of your site's hugo.toml is used.
+disableSourceButton = false
+
+# Hide the Print button.
+# Default: false
+# This hides the print button if you activated the print output format.
+# If not set, the set value of your site's hugo.toml is used.
+disablePrintButton = false
+
+# Hide Next and Previous navigation buttons.
+# Default: false
+# If the navigation buttons are hidden, also the keyboard shortcuts are
+# disabled.
+disableNextPrev = false
+
+# The URL prefix to edit a page.
+# Default: not set
+# If set, an edit button will be shown in the topbar. If the button is hidden,
+# also the keyboard shortcuts are disabled. The value can contain the macro
+# `${FilePath}` which will be replaced by the file path of your displayed page.
+# If not set, the set value of your site's hugo.toml is used. If the global
+# parameter is given but you want to hide the button for the displayed page,
+# you can set the value to an empty string. If instead of hiding you want to have
+# an disabled button, you can set the value to a string containing just spaces.
+# This is useful if you want to give the opportunity for people to create merge
+# request for your content.
+editURL = ''
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Menu
+# These options modify the menu appearance.
+
+# Menu specific title
+# Default: not set
+# The title displayed in the menu. If not set the `title` front matter will
+# be used.
+linkTitle = ''
+
+# Prefix for the title in navigation menu.
+# Default: not set
+# The title of the page in the menu will be prefixed by this HTML content.
+menuPre = ''
+
+# Suffix for the title in navigation menu.
+# Default: not set
+# The title of the page in the menu will be suffixed by this HTML content.
+menuPost = ''
+
+# Link the menu entry to a different internal page instead.
+# Default: not set
+# This will effectivly hide the page and its content from the viewer by
+# linking to the given URL instead.
+menuPageRef = ''
+
+# Link the menu entry to an external URL instead of a page.
+# Default: not set
+# This will effectivly hide the page and its content from the viewer by
+# linking to the given URL instead.
+menuUrl = ''
+
+# The order of navigation menu submenus.
+# Default: 'weight'
+# Submenus can be ordered by 'weight', 'title', 'linktitle', 'modifieddate',
+# 'expirydate', 'publishdate', 'date', 'length' or 'default' (adhering to
+# Hugo's default sort order).
+# If not set, the value of the parent menu entry is used.
+ordersectionsby = 'weight'
+
+# The initial expand state of submenus.
+# Default: not set
+# This controls whether submenus will be expanded (true), or collapsed (false)
+# in the menu. If not set, the first menu level is set to false, all others
+# levels are set to true. If not set, the value of the parent menu entry is used.
+# If the displayed page has submenus, they will always been displayed expanded
+# regardless of this option.
+alwaysopen = ''
+
+# Shows expander for submenus.
+# Default: false
+# If set to true, a submenu in the sidebar will be displayed in a collapsible
+# tree view and a clickable expander is set in front of the entry.
+# If not set, the set value of your site's hugo.toml is used.
+collapsibleMenu = true
+
+# Define your own sidebar menus.
+# Default: the value used below
+# The sidebar menus are built from this parameter. If not set, the set value
+# of your site's hugo.toml is used and contains the below default.
+# Menus are written from the sidebar's top to buttom in the order given in
+# this array.
+# Each entry can contain the following keys:
+# - `type` is mandatory. Either `page` in case it should generate a tre from
+#    the page structure or `menu` in case it should generate a tree from a
+#    defined menu.
+# - `identifier` is mandatory. In case of `type=page`, anything can be used,
+#    in case of `type=menu` the `identifier` key must be identical to the
+#    key of the menu definition.
+# - `main`, boolean. If `true`, the first tree level is spaced more generous
+#    and the text is emphasized. Default: `true` for `type=page` and `false`
+#    for `type=menu`
+# - `disableTitle`, boolean. If `true`, there is no title above the tree.
+#    Default: `true` for `type=page` and `false` for `type=menu`. If a title
+#    should be used, in case of `type=page` it will be taken from the page's
+#    `menuTitle` front matter and if not set, from the translation files, using
+#    the menu `identifier` as key. In case of `type=menu` it will be taken
+#    from the menu `title` according to Hugo's documentation and if not set
+#    from the menu `name` and if this is not set form the page's `linkTitle`.
+# - `pageRef`, optional. In case of `type=page` this is the starting page's
+#   path. If not set, the home page will be used.
+sidebarmenus = [
+	{ type = 'page', identifier = 'home', main = true, disableTitle = true, pageRef = '' },
+	{ type = 'menu', identifier = 'shortcuts', main = false, disableTitle = false },
+]
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Hidden pages
+# These options configure how hidden pages are treated.
+# A page flagged as hidden, is only removed from the navigation menu if you are
+# currently not on this page or the hidden page is not part of current page's
+# ancestors. For all other functionality in Hugo a hidden page behaves like any
+# other page if not otherwise configured.
+
+# Hide a page's menu entry.
+# Default: false
+# If this value is true, the page is hidden from the menu.
+hidden = false
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Content
+# These options modify how your content is displayed.
+
+# Prefix for the title in the content area.
+# Default: not set
+# The title of the page heading will be prefixed by this HTML content.
+headingPre = ''
+
+# Suffix for the title in the content area.
+# Default: not set
+# The title of the page heading will be suffixed by this HTML content.
+headingPost = ''
+
+# Display name of the page's last editor.
+# Default: not set
+# If set, it will be displayed in the default footer.
+LastModifierDisplayName = ''
+
+# Email address of the page's last editor.
+# Default: not set
+# If set together with LastModifierDisplayName, it will be displayed in the
+# default footer.
+LastModifierEmail = ''
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Highlight
+# These options configure how code is displayed.
+
+# Wrap for code blocks.
+# Default: true
+# By default lines of code blocks wrap around if the line is too long to be
+# displayed on screen. If you dislike this behavior, you can reconfigure it
+# here.
+# Note that lines always wrap in print mode regardless of this option.
+# If not set, the set value of your site's hugo.toml is used or given as a
+# parameter to individual code blocks.
+highlightWrap = true
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Include
+# These options configure how the include shortcode works.
+
+# What to do when path is not resolved.
+# Default: ''
+# You can control what should happen if a path can not be resolved to as
+# a resource or via the file system. If not set, no output will be written
+# for the unresolved path. If set to `warning` the same happens and an additional
+# warning is printed. If set to `error` an error message is printed and the build
+# is aborted.
+# If not set, the set value of your site's hugo.toml is used.
+include.errorlevel = ''
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Images
+# These options configure how images are displayed.
+
+# What to do when local image link is not resolved.
+# Default: ''
+# You can control what should happen if a local image can not be resolved to as
+# a resource. If not set, the unresolved link is written as given into the resulting
+# output. If set to `warning` the same happens and an additional warning is
+# printed. If set to `error` an error message is printed and the build is
+# aborted.
+# Please note that this can not resolve files inside of your `static` directory.
+# If not set, the set value of your site's hugo.toml is used.
+image.errorlevel = ''
+
+# Image effects.
+# See the documentation for how you can even add your own arbitrary effects to
+# the list.
+# All effect values default to the values of your site's hugo.toml and can be
+# overridden through URL parameter given to the image. See the documentation for
+# details.
+
+# Default: false
+imageEffects.border = true
+# Default: true
+imageEffects.lazy = true
+# Default: true
+imageEffects.lightbox = true
+# Default: false
+imageEffects.shadow = false
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Links
+# These options configure how links are displayed.
+
+# What to do when local page link is not resolved.
+# Default: ''
+# You can control what should happen if a local link can not be resolved to a
+# page. If not set, the unresolved link is written as given into the resulting
+# output. If set to `warning` the same happens and an additional warning is
+# printed. If set to `error` an error message is printed and the build is
+# aborted.
+# Please note that with Hugo < 0.123.0 + `uglyURLs=true` this can lead to false
+# negatives.
+# If not set, the set value of your site's hugo.toml is used.
+link.errorlevel = ''
+
+# How to open external links.
+# Default: '_blank'
+# For external links you can define how they are opened in your browser. All
+# values for the HTML `target` attribute of the `a` element are allowed. The
+# default value opens external links in a separate browser tab. If you want
+# to open those links in the same tab, use '_self'.
+# If not set, the set value of your site's hugo.toml is used.
+externalLinkTarget = '_self'
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# MathJax
+# These options configure how math formulae are displayed.
+
+# Initialization options for MathJax.
+# Default: not set
+# A JSON value. See the MathJaxdocumentation for possible parameter.
+# If not set, the set value of your site's hugo.toml is used.
+mathJaxInitialize = '{}'
+
+# Force load Math on every page.
+# Default: false
+# If a, Math shortcode or codefence is found, the option will be ignored and
+# Math will be loaded regardlessly. This option is useful in case you
+# are using passthrough configuration to render your math. In this case no shortcode or
+# codefence is involved and the library is not loaded by default so you can
+# force loading it by setting `math=true`.
+# This option has an alias `math.force`.
+# If not set, the set value of your site's hugo.toml is used.
+math = false
+
+# URL for external MathJax library.
+# Default: not set
+# Specifies the remote location of the MathJax library. By default the shipped
+# version will be used.
+# If not set, the set value of your site's hugo.toml is used.
+customMathJaxURL = '' # 'https://unpkg.com/mathjax/es5/tex-mml-chtml.js'
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# Mermaid
+# These options configure how Mermaid graphs are displayed.
+
+# Make graphs panable and zoomable
+# Default: false
+# For huge graphs it can be helpful to make them zoomable. Zoomable graphs come
+# with a reset button for the zoom.
+# If not set, the set value of your site's hugo.toml is used or given as a
+# parameter to individual graphs.
+mermaidZoom = true
+
+# Initialization options for Mermaid.
+# Default: not set
+# A JSON value. See the Mermaid documentation for possible parameter.
+# If not set, the set value of your site's hugo.toml is used.
+mermaidInitialize = '{ "securityLevel": "loose" }'
+
+# Force load Mermaid on every page.
+# Default: false
+# If a Mermaid shortcode or codefence is found, the option will be ignored and
+# Mermaid will be loaded regardlessly. This option is useful in case you
+# are using scripting to render your graph. In this case no shortcode or
+# codefence is involved and the library is not loaded by default so you can
+# force loading it by setting `mermaid.force=true`.
+# If not set, the set value of your site's hugo.toml is used.
+mermaid.force = false
+
+# URL for external Mermaid library.
+# Default: not set
+# Specifies the remote location of the Mermaid library. By default the shipped
+# version will be used.
+# If not set, the set value of your site's hugo.toml is used.
+customMermaidURL = '' # 'https://unpkg.com/mermaid/dist/mermaid.min.js'
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+# OpenApi
+# These options configure how OpenAPI specifications are displayed.
+
+# Load OpenAPI on every page.
+# Default: false
+# If a, OpenAPI shortcode or codefence is found, the option will be ignored and
+# OpenAPI will be loaded regardlessly. This option is useful in case you
+# are using scripting to render your spec. In this case no shortcode or
+# codefence is involved and the library is not loaded by default so you can
+# force loading it by setting `openapi.force=true`.
+# If not set, the set value of your site's hugo.toml is used.
+openapi.force = false
+
+# URL for external OpenAPI library.
+# Default: not set
+# Specifies the remote location of the OpenAPI library. By default the shipped
+# version will be used.
+# If not set, the set value of your site's hugo.toml is used.
+customOpenapiURL = '' # 'https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js'
+
+# What to do when a local OpenAPI spec link is not resolved.
+# Default: ''
+# You can control what should happen if a local OpenAPI spec link can not be resolved
+# to a resource. If not set, the unresolved link is written as given into the resulting
+# output. If set to `warning` the same happens and an additional warning is
+# printed. If set to `error` an error message is printed and the build is
+# aborted.
+# Please note that this can not resolve files inside of your `static` directory.
+# If not set, the set value of your site's hugo.toml is used.
+openapi.errorlevel = ''

docs/content/authoring/frontmatter/topbar/_index.en.md

@@ -0,0 +1,84 @@
++++
+categories = ["howto"]
+description = "Configure the topbar"
+frontmatter = ["disableBreadcrumb", "disableNextPrev", "disableMarkdownButton", "disableSourceButton", "disablePrintButton", "disableToc", "editURL"]
+options = ["disableBreadcrumb", "disableNextPrev", "disableMarkdownButton", "disableSourceButton", "disablePrintButton", "disableToc", "editURL"]
+outputs = ["html", "rss", "print", "markdown", "source"]
+title = "Topbar"
+weight = 4
++++
+
+This page is about how to configure the topbar using configuration options. If you want to add further buttons or functionality, [see this section](configuration/customization/topbar).
+
+Your topbar contains the following elements. Some of them are configuarable:
+
+- {{% button style="transparent" icon="bars" %}}{{% /button %}} **sidebar**: opens the sidebar flyout if in mobile layout
+- {{% button style="transparent" icon="list-alt" %}}{{% /button %}} **toc**: [opens the table of contents in an overlay](#table-of-contents)
+- {{% button style="transparent" icon="empty" %}}{{% /button %}} **breadcrumb**: shows the clickable [breadcrumbs](#breadcrumbs)
+- {{% button style="transparent" icon="pen" %}}{{% /button %}} **edit**: browses to the editable page if the `editURL` [parameter is set](#edit-button)
+- {{% button style="transparent" icon="file-code" %}}{{% /button %}} **source**: browses to the [chapters source code](#source-button) if [source support](configuration/sitemanagement/outputformats#source-support) was activated
+- {{% button style="transparent" icon="fa-fw fab fa-markdown" %}}{{% /button %}} **markdown**: browses to the [chapters Markdown source](#markdown-button) if [markdown support](configuration/sitemanagement/outputformats#markdown-support) was activated
+- {{% button style="transparent" icon="print" %}}{{% /button %}} **print**: browses to the [chapters printable page](#print-button) if [print support](configuration/sitemanagement/outputformats#print-support) was activated
+- {{% button style="transparent" icon="chevron-left" %}}{{% /button %}} **prev**: browses to the [previous page](#arrow-navigation) if there is one
+- {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} **next**: browses to the [next page](#arrow-navigation) if there is one
+- {{% button style="transparent" icon="ellipsis-v" %}}{{% /button %}} **more**: opens the overlay if screen space is limited
+
+## Table of Contents
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Set `disableToc=true` to hide the TOC button on all pages. If the button is hidden, also the keyboard shortcut is disabled. This can be overridden in a page's front matter.
+
+{{< multiconfig >}}
+disableToc = true
+{{< /multiconfig >}}
+
+## Breadcrumbs
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Set `disableBreadcrumb=true` to hide the breadcrumb in the topbar.
+
+Further breadcrumbs settings can be found in the [content configuration section](configuration/content/titles).
+
+{{< multiconfig >}}
+disableBreadcrumb = true
+{{< /multiconfig >}}
+
+## Edit Button
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} If `editURL` is set to a URL, an edit button will be shown in the topbar. If the button is hidden, also the keyboard shortcut is disabled.
+
+The value can contain the macro `${FilePath}` which will be replaced by the file path of your displayed page. If no `${FilePath}` is given in the value, the value is treated as if the `${FilePath}` was appended at the end of the value. This can be overridden in the pages front matter.
+
+{{< multiconfig >}}
+editURL = 'https://github.com/McShelby/hugo-theme-relearn/edit/main/docs/content/${FilePath}'
+{{< /multiconfig >}}
+
+## Markdown Button
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can hide the Markdown button if the [Markdown output format](configuration/sitemanagement/outputformats/#markdown-support) is active by setting `disableMarkdownButton=true`.
+
+{{< multiconfig >}}
+disableMarkdownButton = true
+{{< /multiconfig >}}
+
+## Source Button
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can hide the Source button if the [Source output format](configuration/sitemanagement/outputformats/#source-support) is active by setting `disableSourceButton=true`.
+
+{{< multiconfig >}}
+disableSourceButton = true
+{{< /multiconfig >}}
+
+## Print Button
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can hide the print button if the [print output format](configuration/sitemanagement/outputformats/#print-support) is active by setting `disablePrintButton=true`.
+
+{{< multiconfig >}}
+disablePrintButton = true
+{{< /multiconfig >}}
+
+## Arrow Navigation
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can hide the previous/next buttons by setting `disableNextPrev=true`. If the buttons are hidden, also the keyboard shortcuts are disabled.
+
+{{< multiconfig >}}
+disableNextPrev = true
+{{< /multiconfig >}}

docs/content/authoring/frontmatter/topbar/_index.pir.md

@@ -0,0 +1,10 @@
++++
+categories = ["howto"]
+description = "Configure the topbar"
+frontmatter = ["disableBreadcrumb", "disableNextPrev", "disableMarkdownButton", "disableSourceButton", "disablePrintButton", "disableToc", "editURL"]
+options = ["disableBreadcrumb", "disableNextPrev", "disableMarkdownButton", "disableSourceButton", "disablePrintButton", "disableToc", "editURL"]
+outputs = ["html", "rss", "print", "markdown", "source"]
+title = "Topbarrr"
+weight = 4
++++
+{{< piratify >}}

docs/content/authoring/imageeffects.en.md

@@ -0,0 +1,58 @@
++++
+categories = ["explanation"]
+description = "How to apply graphical effects to your images"
+frontmatter = ["imageEffects"]
+title = "Image Effects"
+weight = 5
++++
+
+The theme offers [graphical effects](authoring/markdown#image-effects) for your linked images.
+
+You can [define additional custom image effects and set defaults](configuration/customization/imageeffects) in your configuration.
+
+The default image effects shipped with the theme are
+
+| Name     | Description                                                       |
+| -------- | ----------------------------------------------------------------- |
+| border   | Draws a light thin border around the image                        |
+| lazy     | Lets the image be lazy loaded                                     |
+| lightbox | The image will be clickable to show it enlarged                   |
+| shadow   | Draws a shadow around the image to make it appear hovered/glowing |
+
+One way to use them is to add them as URL query parameter to each individually linked image.
+
+This can become cumbersome to be done consistently for the whole site. Instead, you can [configure the defaults](configuration/customization/imageeffects) 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 >}}
+[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 for example by
+
+{{< multiconfig fm=true >}}
+[imageEffects]
+  lazy = false
+{{< /multiconfig >}}
+
+Or by explicitly override settings by URL query parameter
+
+````md {title="URL"}
+![Minion](https://octodex.github.com/images/minion.png?lazy=true&lightbox=false)
+````
+
+The settings applied to the above image would be
+
+{{< multiconfig >}}
+border = true
+lazy = true
+lightbox = false
+shadow = false
+{{< /multiconfig >}}

docs/content/authoring/imageeffects.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["explanation"]
+description = "How to apply graphical effects to your images"
+frontmatter = ["imageEffects"]
+title = "Image Effects"
+weight = 5
++++
+{{< piratify >}}

docs/content/authoring/markdown.en.md

@@ -0,0 +1,849 @@
++++
+description = "Reference of CommonMark and Markdown extensions"
+categories = ["howto", "reference"]
+title = "Markdown Syntax"
+weight = 4
++++
+
+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.
+
+**Markdown** is a better way to write **HTML**, without all the complexities and ugliness that usually accompanies it.
+
+Some of the key benefits are:
+
+1. Markdown is simple to learn, with minimal extra characters so it's also quicker to write content.
+2. Less chance of errors when writing in Markdown.
+3. Produces valid HTML output.
+4. Keeps the content and the visual display separate, so you cannot mess up the look of your site.
+5. Write in any text editor or Markdown application you like.
+6. Markdown is a joy to use!
+
+John Gruber, the author of Markdown, puts it like this:
+
+> The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. While Markdown's syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown's syntax is the format of plain text email.
+> <cite>John Gruber</cite>
+
+{{% notice tip %}}
+{{% icon bookmark %}} Bookmark this page for easy future reference!
+{{% /notice %}}
+
+## Standard and Extensions
+
+If not otherwise noted, the shown examples adhere to the [CommonMark](https://commonmark.org/help/) standard. In addition the theme supports the following extensions that [can be activated](https://gohugo.io/getting-started/configuration-markup/#goldmark) in your `hugo.toml` or are built into the theme:
+
+- {{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Extension on top of standard Markdown adhering to [GitHub Flavored Markdown](https://github.github.com/gfm/).
+
+- {{% badge color="#888cc4" icon="fa-fw fab fa-php" %}}PHP{{% /badge %}} Extension on top of standard Markdown adhering to [PHP Markdown](https://michelf.ca/projects/php-markdown/extra/).
+
+- {{% badge color="darkorange" icon="lightbulb" %}}Pants{{% /badge %}} Extension by John Gruber adhering to [SmartyPants](https://daringfireball.net/projects/smartypants/).
+
+- {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Hugo{{% /badge %}} [Hugo Extra Extension](https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension) supported by Hugo.
+
+- {{% badge color="#7c3aed" icon="fa-fw far fa-gem" %}}Obsidian{{% /badge %}} Extension implemented by [Obsidian](https://obsidian.md/).
+
+- {{% badge color="orangered" icon="fa-fw fas fa-code" %}}HTML{{% /badge %}} If the [usage of HTML](https://gohugo.io/getting-started/configuration-markup/#rendererunsafe) is allowed, the theme supports styling for further HTML elements.
+
+- {{% badge color="#7dc903" icon="fa-fw fas fa-puzzle-piece" %}}Relearn{{% /badge %}} Extension specific to this theme.
+
+## Paragraphs
+
+In Markdown your content usually spans the whole available document width. This is called a block. Blocks are always separated by whitespace to their adjacent blocks in the resulting document.
+
+Any text not starting with a special sign is written as normal, plain text paragraph block and must be separated to its adjacent blocks by empty lines.
+
+````md
+Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
+
+Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
+
+Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
+{{% /notice %}}
+
+## Headings
+
+A good idea is to structure your content using headings and subheadings. HTML-headings from `h1` through `h6` are constructed with a `#` for each level.
+
+In Hugo you usually don't use `h1` as this is generated by your theme and you should only have one such element in a document.
+
+````md
+# h1 Heading
+
+## h2 Heading
+
+### h3 Heading
+
+#### h4 Heading
+
+##### h5 Heading
+
+###### h6 Heading
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+
+# h1 Heading
+
+## h2 Heading
+
+### h3 Heading
+
+#### h4 Heading
+
+##### h5 Heading
+
+###### h6 Heading
+{{% /notice %}}
+
+## Horizontal Rules
+
+To further structure your content you can add horizontal rules. They create a "thematic break" between paragraph blocks. In Markdown, you can create it with three consecutive dashes `---`.
+
+````md
+Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
+
+---
+
+Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
+
+---
+
+Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
+{{% /notice %}}
+
+## Blockquotes
+
+### Quotations
+
+For quoting blocks of content from another source within your document add `>` before any text you want to quote.
+
+Blockquotes can also be nested.
+
+````md
+> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.
+>
+> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
+>
+> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.
+>
+> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
+>
+> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
+{{% /notice %}}
+
+### GitHub Alerts
+
+{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Since Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}0.132.0{{% /badge %}} [GitHub alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) are also supported. Please note, that coloring and icons of severities may defer between GitHub and this theme.
+
+If you are in need of more advanced options to style your alerts, like icons, use the [notice shortcode](shortcodes/notice).
+
+````md
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!INFO]
+> Information that users <ins>_might_</ins> find interesting.
+
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!INFO]
+> Information that users <ins>_might_</ins> find interesting.
+
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+{{% /notice %}}
+
+### Obsidian Callouts
+
+{{% badge color="#7c3aed" icon="fa-fw far fa-gem" %}}Obsidian{{% /badge %}} Since Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}0.134.0{{% /badge %}} [Obsidian callouts](https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title) are also supported. Which enables configurable title text and expand/collapse.
+
+If you are in need of more advanced options to style your alerts, like icons, use the [notice shortcode](shortcodes/notice).
+
+````md
+> [!tip] Callouts can have custom titles
+> Like this one.
+
+> [!tip] Title-only callout
+
+> [!note]- Are callouts foldable?
+> Yes! In a foldable callout, the contents are hidden when the callout is collapsed
+
+> [!note]+ Are callouts foldable?
+> Yes! In a foldable callout, the contents are hidden when the callout is collapsed
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+> [!tip] Callouts can have custom titles
+> Like this one.
+
+> [!tip] Title-only callout
+
+> [!note]- Are callouts foldable?
+> Yes! In a foldable callout, the contents are hidden when the callout is collapsed
+
+> [!note]+ Are callouts foldable?
+> Yes! In a foldable callout, the contents are hidden when the callout is collapsed
+{{% /notice %}}
+
+## Text Markers
+
+### Bold
+
+You can show importance of a snippet of text with a heavier font-weight by enclosing it with two asterisks `**`.
+
+````md
+I am rendered with **bold text**
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+I am rendered with **bold text**
+{{% /notice %}}
+
+### Italics
+
+You can emphasize a snippet of text with italics by enclosing it with underscores `_`.
+
+````md
+I am rendered with _italicized text_
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+I am rendered with _italicized text_
+{{% /notice %}}
+
+### Marked Text
+
+You can mark text in the predefined accent color of your stylesheet.
+
+{{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Hugo{{% /badge %}} Since Hugo 0.126.0, you can [activate this through the _Hugo Extra Extension_](https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension) in your `hugo.toml`
+
+````md
+==Parts== of this text ==are marked!==
+````
+
+{{% badge color="orangered" icon="fa-fw fas fa-code" %}}HTML{{% /badge %}} You can also use it by configuring Hugo for [usage of HTML](https://gohugo.io/getting-started/configuration-markup/#rendererunsafe).
+
+````html
+<mark>Parts</mark> of this text <mark>are marked!</mark>
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+<mark>Parts</mark> of this text <mark>are marked!</mark>
+{{% /notice %}}
+
+### Inserted Text
+
+You can mark text additions to existing text.
+
+{{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Hugo{{% /badge %}} Since Hugo 0.126.0, you can [activate this through the _Hugo Extra Extension_](https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension) in your `hugo.toml`
+
+````md
+The ++hot, new++ stuff
+````
+
+{{% badge color="orangered" icon="fa-fw fas fa-code" %}}HTML{{% /badge %}} You can also use it by configuring Hugo for [usage of HTML](https://gohugo.io/getting-started/configuration-markup/#rendererunsafe).
+
+````html
+The <ins>hot, new</ins> stuff
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+The ++hot, new++ stuff
+{{% /notice %}}
+
+### Deleted Text
+
+{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} You can do strikethroughs by enclosing text with two tildes `~~`. See [Hugo's documentation remarks](https://gohugo.io/getting-started/configuration-markup/#extras) if you want to use this together with the subscript syntax.
+
+````md
+~~Strike through~~ this text
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+~~Strike through~~ this text
+{{% /notice %}}
+
+## Special Typesetting
+
+### Text Substitution
+
+{{% badge color="darkorange" icon="lightbulb" %}}Pants{{% /badge %}} You can combine multiple punctuation characters to single typographic entities. This will only be applied to text outside of code blocks or inline code.
+
+````md
+Double quotes `"` and single quotes `'` of enclosed text are replaced by **"double curly quotes"** and **'single curly quotes'**.
+
+Double dashes `--` and triple dashes `---` are replaced by en-dash **--** and em-dash **---** entities.
+
+Double arrows pointing left `<<` or right `>>` are replaced by arrow **<<** and **>>** entities.
+
+Three consecutive dots `...` are replaced by an ellipsis **...** entity.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+Double quotes `"` and single quotes `'` of enclosed text are replaced by **"double curly quotes"** and **'single curly quotes'**.
+
+Double dashes `--` and triple dashes `---` are replaced by en-dash **--** and em-dash **---** entities.
+
+Double arrows pointing left `<<` or right `>>` are replaced by arrow **<<** and **>>** entities.
+
+Three consecutive dots `...` are replaced by an ellipsis **...** entity.
+{{% /notice %}}
+
+### Subscript and Superscript
+
+You can also use  subscript and superscript text. For more complex stuff, you can use the [`math` shortcode](shortcodes/math).
+
+{{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Hugo{{% /badge %}} Since Hugo 0.126.0, you can [activate this through the _Hugo Extra Extension_](https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension) in your `hugo.toml`
+
+````md
+How many liters H~2~O fit into 1dm^3^?
+````
+
+{{% badge color="orangered" icon="fa-fw fas fa-code" %}}HTML{{% /badge %}} You can also use it by configuring Hugo for [usage of HTML](https://gohugo.io/getting-started/configuration-markup/#rendererunsafe).
+
+````html
+How many liters H<sub>2</sub>O fit into 1dm<sup>3</sup>?
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+How many liters H~2~O fit into 1dm^3^?
+{{% /notice %}}
+
+### Keyboard Shortcuts
+
+{{% badge color="orangered" icon="fa-fw fas fa-code" %}}HTML{{% /badge %}} You can use the `<kbd>` element to style keyboard shortcuts.
+
+````html
+Press <kbd>STRG</kbd> <kbd>ALT</kbd> <kbd>DEL</kbd> to end your shift early.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+Press <kbd>STRG</kbd> <kbd>ALT</kbd> <kbd>DEL</kbd> to end your shift early.
+{{% /notice %}}
+
+## Lists
+
+### Unordered
+
+You can write a list of items in which the order of the items does not explicitly matter.
+
+It is possible to nest lists by indenting an item for the next sublevel.
+
+You may use any of `-`, `*` or `+` to denote bullets for each list item but should not switch between those symbols inside one whole list.
+
+````md
+- Lorem ipsum dolor sit amet
+- Consectetur adipiscing elit
+  - Vestibulum laoreet porttitor sem
+  - Ac tristique libero volutpat at
+- Nulla volutpat aliquam velit
+  - Phasellus iaculis neque
+  - Purus sodales ultricies
+- Faucibus porta lacus fringilla vel
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+- Lorem ipsum dolor sit amet
+- Consectetur adipiscing elit
+  - Vestibulum laoreet porttitor sem
+  - Ac tristique libero volutpat at
+- Nulla volutpat aliquam velit
+  - Phasellus iaculis neque
+  - Purus sodales ultricies
+- Faucibus porta lacus fringilla vel
+{{% /notice %}}
+
+### Ordered
+
+You can create a list of items in which the order of items does explicitly matter.
+
+It is possible to nest lists by indenting an item for the next sublevel.
+
+Markdown will automatically number each of your items consecutively. This means, the order number you are providing is irrelevant.
+
+````md
+1. Lorem ipsum dolor sit amet
+3. Consectetur adipiscing elit
+    1. Integer molestie lorem at massa
+    7. Facilisis in pretium nisl aliquet
+99. Nulla volutpat aliquam velit
+    1. Faucibus porta lacus fringilla vel
+    1. Aenean sit amet erat nunc
+17. Eget porttitor lorem
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+1. Lorem ipsum dolor sit amet
+1. Consectetur adipiscing elit
+    1. Integer molestie lorem at massa
+    7. Facilisis in pretium nisl aliquet
+99. Nulla volutpat aliquam velit
+    1. Faucibus porta lacus fringilla vel
+    1. Aenean sit amet erat nunc
+17. Eget porttitor lorem
+{{% /notice %}}
+
+### Tasks
+
+{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} You can add task lists resulting in checked or unchecked non-clickable items
+
+````md
+- [x] Basic Test
+- [ ] More Tests
+  - [x] View
+  - [x] Hear
+  - [ ] Smell
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+- [x] Basic Test
+- [ ] More Tests
+  - [x] View
+  - [x] Hear
+  - [ ] Smell
+{{% /notice %}}
+
+### Definitions
+
+{{% badge color="#888cc4" icon="fa-fw fab fa-php" %}}PHP{{% /badge %}} Definition lists are made of terms and definitions of these terms, much like in a dictionary.
+
+A definition list in Markdown Extra is made of a single-line term followed by a colon and the definition for that term. You can also associate more than one term to a definition.
+
+If you add empty lines around the definition terms, additional vertical space will be generated. Also multiple paragraphs are possible
+
+````md
+Apple
+: Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
+: An American computer company.
+
+Orange
+: The fruit of an evergreen tree of the genus Citrus.
+
+  You can make juice out of it.
+: A telecommunication company.
+
+  You can't make juice out of it.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+Apple
+: Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
+: An American computer company.
+
+Orange
+: The fruit of an evergreen tree of the genus Citrus.
+
+  You can make juice out of it.
+: A telecommunication company.
+
+  You can't make juice out of it.
+{{% /notice %}}
+
+## Code
+
+### Inline Code
+
+Inline snippets of code can be wrapped with backticks `` ` ``.
+
+````md
+In this example, `<div></div>` is marked as code.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+In this example, `<div></div>` is marked as code.
+{{% /notice %}}
+
+### Indented Code Block
+
+A simple code block can be generated by indenting several lines of code by at least two spaces.
+
+````md
+Be impressed by my advanced code:
+
+    // Some comments
+    line 1 of code
+    line 2 of code
+    line 3 of code
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+Be impressed by my advanced code:
+
+    // Some comments
+    line 1 of code
+    line 2 of code
+    line 3 of code
+{{% /notice %}}
+
+### Fenced Code Block
+
+If you want to gain more control of your code block you can enclose your code by at least three backticks ```` ``` ```` a so called fence.
+
+{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} You can also add a language specifier directly after the opening fence, ` ```js `, and syntax highlighting will automatically be applied according to the selected language in the rendered HTML.
+
+See [Code Highlighting](shortcodes/highlight) for additional documentation.
+
+````plaintext
+```js
+{
+    name: "Claus",
+    surname: "Santa",
+    profession: "courier",
+    age: 666,
+    address: {
+        city: "North Pole",
+        postalCode: 1,
+        country: "Arctic"
+    },
+    friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ]
+};
+```
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+```js
+{
+    name: "Claus",
+    surname: "Santa",
+    profession: "courier",
+    age: 666,
+    address: {
+        city: "North Pole",
+        postalCode: 1,
+        country: "Arctic"
+    },
+    friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ]
+};
+```
+{{% /notice %}}
+
+## Tables
+
+{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} You can create tables by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned.
+
+````md
+| Option | Description |
+|--------|-------------|
+| data   | path to data files to supply the data that will be passed into templates. |
+| engine | engine to be used for processing templates. Handlebars is the default. |
+| ext    | extension to be used for dest files. |
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+| Option | Description |
+|--------|-------------|
+| data   | path to data files to supply the data that will be passed into templates. |
+| engine | engine to be used for processing templates. Handlebars is the default. |
+| ext    | extension to be used for dest files. |
+{{% /notice %}}
+
+### Aligned Columns
+
+Adding a colon on the left and/or right side of the dashes below any heading will align the text for that column accordingly.
+
+````md
+| Option | Number | Description |
+|-------:|:------:|:------------|
+| data   | 1      | path to data files to supply the data that will be passed into templates. |
+| engine | 2      | engine to be used for processing templates. Handlebars is the default. |
+| ext    | 3      | extension to be used for dest files. |
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+| Option | Number | Description |
+|-------:|:------:|:------------|
+| data   | 1      | path to data files to supply the data that will be passed into templates. |
+| engine | 2      | engine to be used for processing templates. Handlebars is the default. |
+| ext    | 3      | extension to be used for dest files. |
+{{% /notice %}}
+
+## Links
+
+### Autolink
+
+{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Absolute URLs will automatically be converted into a link.
+
+````md
+This is a link to https://example.com.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+This is a link to https://example.com.
+{{% /notice %}}
+
+
+### Basic Link
+
+You can explicitly define links in case you want to use non-absolute URLs or want to give different text.
+
+````md
+[Assemble](http://assemble.io)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+[Assemble](http://assemble.io)
+{{% /notice %}}
+
+### Link with Tooltip
+
+For even further information, you can add an additional text, displayed in a tooltip on hovering over the link.
+
+````md
+[Upstage](https://github.com/upstage/ "Visit Upstage!")
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+[Upstage](https://github.com/upstage/ "Visit Upstage!")
+{{% /notice %}}
+
+### Link References
+
+Links can be simplyfied for recurring reuse by using a reference ID to later define the URL location. This simplyfies writing if you want to use a link more than once in a document.
+
+````md
+[Example][somelinkID]
+
+[somelinkID]: https://example.com "Go to example domain"
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+[Example][somelinkID]
+
+[somelinkID]: https://example.com "Go to example domain"
+{{% /notice %}}
+
+### Footnotes
+
+{{% badge color="#888cc4" icon="fa-fw fab fa-php" %}}PHP{{% /badge %}} Footnotes work mostly like reference-style links. A footnote is made of two things, a marker in the text that will become a superscript number and a footnote definition that will be placed in a list of footnotes.
+
+Usually the list of footnotes will be shown at the end of your document. If we use a footnote in a notice box it will instead be listed at the end of its box.
+
+Footnotes can contain block elements, which means that you can put multiple paragraphs, lists, blockquotes and so on in a footnote. It works the same as for list items, just indent the following paragraphs by four spaces in the footnote definition.
+
+````md
+That's some text with a footnote[^1]
+
+[^1]: And that's the footnote.
+
+That's some more text with a footnote.[^someid]
+
+[^someid]:
+    Anything of interest goes here.
+
+    Blue light glows blue.
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+That's some text with a footnote[^1]
+
+[^1]: And that's the footnote.
+
+That's some more text with a footnote.[^someid]
+
+[^someid]:
+    Anything of interest goes here.
+
+    Blue light glows blue.
+{{% /notice %}}
+
+## Images
+
+### Basic Images
+
+Images have a similar syntax to links but include a preceding exclamation mark.
+
+````md
+![Spock](https://octodex.github.com/images/spocktocat.png)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Spock](https://octodex.github.com/images/spocktocat.png?width=20vw)
+{{% /notice %}}
+
+### Image with Tooltip
+
+Like links, images can also be given a tooltip.
+
+````md
+![Picard](https://octodex.github.com/images/jean-luc-picat.jpg "Jean Luc Picard")
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Picard](https://octodex.github.com/images/jean-luc-picat.jpg?width=20vw "Jean Luc Picard")
+{{% /notice %}}
+
+### Image References
+
+Images can also be linked by reference ID to later define the URL location. This simplyfies writing if you want to use an image more than once in a document.
+
+````md
+![La Forge][laforge]
+
+[laforge]: https://octodex.github.com/images/trekkie.jpg "Geordi La Forge"
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![La Forge][laforge]
+
+[laforge]: https://octodex.github.com/images/trekkie.jpg?width=20vw "Geordi La Forge"
+{{% /notice %}}
+
+### Image Effects
+
+{{% badge color="#7dc903" icon="fa-fw fas fa-puzzle-piece" %}}Relearn{{% /badge %}} This theme allows additional non-standard formatting by setting query parameter at the end of the image URL. See the [image effects docs](authoring/imageeffects) for a detailed example and how to configure it.
+
+#### Resizing
+
+Add query parameter `width` and/or `height` to the link image to resize the image. Values are CSS values (default is `auto`).
+
+````md
+![Minion](https://octodex.github.com/images/minion.png?width=20vw)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Minion](https://octodex.github.com/images/minion.png?width=20vw)
+{{% /notice %}}
+
+````md
+![Minion](https://octodex.github.com/images/minion.png?height=50px)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Minion](https://octodex.github.com/images/minion.png?height=50px)
+{{% /notice %}}
+
+````md
+![Minion](https://octodex.github.com/images/minion.png?height=50px&width=40vw)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Minion](https://octodex.github.com/images/minion.png?height=50px&width=40vw)
+{{% /notice %}}
+
+#### CSS Classes
+
+Add a query parameter `classes` to the link image to add CSS classes. Add some of the predefined values or even define your own in your CSS.
+
+##### Shadow
+
+````md
+![Spidertocat](https://octodex.github.com/images/spidertocat.png?classes=shadow)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Spidertocat](https://octodex.github.com/images/spidertocat.png?width=20vw&classes=shadow,noborder)
+{{% /notice %}}
+
+##### Border
+
+````md
+![DrOctocat](https://octodex.github.com/images/droctocat.png?classes=border)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![DrOctocat](https://octodex.github.com/images/droctocat.png?width=20vw&classes=border,noshadow)
+{{% /notice %}}
+
+##### Left
+
+````md
+![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?classes=left)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?width=20vw&classes=left)
+{{% /notice %}}
+
+##### Right
+
+````md
+![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?classes=right)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?width=20vw&classes=right)
+{{% /notice %}}
+
+##### Inline
+
+````md
+![Spidertocat](https://octodex.github.com/images/spidertocat.png?classes=inline)
+![DrOctocat](https://octodex.github.com/images/droctocat.png?classes=inline)
+![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?classes=inline)
+![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?classes=inline)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Spidertocat](https://octodex.github.com/images/spidertocat.png?width=10vw&classes=inline)
+![DrOctocat](https://octodex.github.com/images/droctocat.png?width=10vw&classes=inline)
+![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?width=10vw&classes=inline)
+![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?width=10vw&classes=inline)
+{{% /notice %}}
+
+##### Combination
+
+````md
+![X-tocat](https://octodex.github.com/images/xtocat.jpg?classes=shadow,border,left)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![X-tocat](https://octodex.github.com/images/xtocat.jpg?width=20vw&classes=shadow,border,left)
+{{% /notice %}}
+
+#### Lightbox
+
+Add the query parameter `lightbox=false` to the image link to disable the lightbox.
+
+````md
+![Homercat](https://octodex.github.com/images/homercat.png?lightbox=false)
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+![Homercat](https://octodex.github.com/images/homercat.png?width=20vw&lightbox=false)
+{{% /notice %}}
+
+{{% notice note %}}
+If you want to wrap an image in a link and `lightbox=true` is your default setting, you have to explicitly disable the lightbox to avoid it to hijacking your link like:
+
+````md
+[![Homercat](https://octodex.github.com/images/homercat.png?lightbox=false)](https://octodex.github.com/#homercat)
+````
+
+[![Homercat](https://octodex.github.com/images/homercat.png?width=20vw&lightbox=false)](https://octodex.github.com/#homercat)
+
+{{% /notice %}}

docs/content/authoring/markdown.pir.md

@@ -0,0 +1,7 @@
++++
+description = "Reference of CommonMark and Markdown extensions"
+categories = ["howto", "reference"]
+title = "Marrrkdown Rules"
+weight = 4
++++
+{{< piratify >}}

docs/content/authoring/meta/_index.en.md

@@ -0,0 +1,71 @@
++++
+categories = ["howto"]
+description = "What page meta information are available"
+frontmatter = ["headingPost", "headingPre", "hidden", "LastModifierDisplayName", "LastModifierEmail"]
+title = "Meta Information"
+weight = 3
++++
+
+## Page Title
+
+The `title` will be used in the heading and meta information of your HTML.
+
+A page without a title is [treated as if `hidden=true`](#hidden) has been set.
+
+{{< multiconfig fm=true >}}
+title = 'Example Title'
+{{< /multiconfig >}}
+
+## Page Description
+
+The `description` is used for generating HTML meta information, in the [children](shortcodes/children) shortcode and in social media meta information.
+
+If not set, the set value of your site's hugo.toml is used for the HTML meta information and social media meta information. It appears empty for the [children](shortcodes/children) shortcode.
+
+{{< multiconfig fm=true >}}
+description = 'Some lenghty example description'
+{{< /multiconfig >}}
+
+## Social Media Images
+
+The theme adds social media meta tags including feature images for the [Open Graph](https://gohugo.io/templates/internal/#open-graph) protocol and [Twitter Cards](https://gohugo.io/templates/internal/#twitter-cards) to your site. These are configured as mentioned in the linked Hugo docs.
+
+{{< multiconfig fm=true >}}
+images = [ 'images/hero.png' ]
+{{< /multiconfig >}}
+
+## Hidden
+
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can hide your pages from the menu by setting `hidden=true`.
+
+{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} For [Hugo menus](https://gohugo.io/content-management/menus/), you have to set `params.hidden=true` instead.
+
+[See how you can further configure visibility](configuration/content/hidden) throughout your site.
+
+{{< multiconfig fm=true >}}
+hidden = true
+{{< /multiconfig >}}
+
+## Add Icon to the Title Heading
+
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} In the page front matter, add a `headingPre` to insert any HTML code before the title heading. You can also set `headingPost` to insert HTML code after the title heading.
+
+You also may want to [apply further CSS](configuration/customization/extending#adding-javascript-or-stylesheets-to-all-pages) in this case.
+
+{{< multiconfig fm=true >}}
+headingPre = '<i class="fab fa-github"></i> '
+{{< /multiconfig >}}
+
+## Footer Information
+
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} If you use the default `layouts/partials/content-footer.html` is not overridden by you, it will display authoring information, namely
+
+- `AuthorName` if [GitInfo](https://gohugo.io/methods/page/gitinfo/) is active, otherwise `LastModifierDisplayName` front matter
+- `AuthorEmail` if [GitInfo](https://gohugo.io/methods/page/gitinfo/) is active, otherwise `LastModifierEmail` front matter
+- `AuthorDate` if [GitInfo](https://gohugo.io/methods/page/gitinfo/) is active, otherwise [Hugo's `date` front matter](https://gohugo.io/methods/page/date/)
+
+{{< multiconfig fm=true >}}
+LastModifierDisplayName = 'Santa Claus'
+LastModifierEmail = 'santa@example.com'
+date = 2000-12-24T00:00:00-12:00
+{{< /multiconfig >}}

docs/content/authoring/meta/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["howto"]
+description = "What page meta information are available"
+frontmatter = ["headingPost", "headingPre", "hidden", "LastModifierDisplayName", "LastModifierEmail"]
+title = "Meta Information"
+weight = 3
++++
+{{< piratify >}}

docs/content/authoring/structure/index.en.md

@@ -0,0 +1,34 @@
++++
+categories = ["explanation"]
+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
+├── first-chapter
+│   ├── first-page
+|   |   |── _index.md
+|   │   ├── first-sub-page
+|   |   |   |── _index.md
+|   |   |   |── picture1.png
+|   |   |   └── plain.txt
+│   ├── second-page
+|   |   |── index.md
+|   |   |── picture1.png
+|   |   └── picture2.png
+│   └── third-page.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.

docs/content/authoring/structure/index.pir.md

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

docs/content/configuration/_index.en.md

@@ -0,0 +1,11 @@
++++
+categories = ["reference"]
+menuPre = "<i class='fa-fw fas fa-gears'></i> "
+title = "Configuration"
+type = "chapter"
+weight = 2
++++
+
+Find out how to configure and customize your site.
+
+{{% children containerstyle="div" style="h2" description=true %}}

docs/content/configuration/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["reference"]
+menuPre = "<i class='fa-fw fas fa-gears'></i> "
+title = "Configurrrat'n"
+type = "chapter"
+weight = 2
++++
+{{< piratify >}}

docs/content/configuration/branding/_index.en.md

@@ -0,0 +1,9 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Change colors and logos of your site"
+title = "Branding"
+weight = 2
++++
+
+{{% children containerstyle="div" style="h2" description=true %}}

docs/content/configuration/branding/_index.pir.md

@@ -0,0 +1,8 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Change colors and logos of your site"
+title = "Brrrand'n"
+weight = 2
++++
+{{< piratify >}}

docs/content/configuration/branding/colors/_index.en.md

@@ -0,0 +1,180 @@
++++
+categories = ["explanation", "howto"]
+description = "Learn how to customize your site's colors"
+options = ["themeVariant"]
+title = "Colors"
+weight = 2
++++
+
+The Relearn theme offers color variants to change your site's appearance. Each color variant contains of a CSS file and optional settings in your `hugo.toml`.
+
+You can use the [shipped variants](#shipped-variants), [customize them](#modifying-variants), or create your own. The [interactive variant generator](configuration/branding/generator) can help you with this.
+
+Once set up in `hugo.toml`, you can switch variants using the selector at the bottom of the menu.
+
+## Shipped Variants
+
+The theme ships with the following set of variants
+
+- Relearn
+  - Light: the classic Relearn default, coming with signature green, dark sidebar and light content area
+  - Dark: dark variant of Light, coming with signature green, dark sidebar and dark content area
+  - Bright: alternative of Light, coming with signature green, green sidebar and light content area
+- Zen
+  - Light: a more relaxed white/grey variant, coming with blue accents, light sidebar and light content area
+  - Dark: dark variant of Light, coming with blue accents, dark sidebar and dark content area
+- Experimental
+  - Neon: a variant that glows in the dark, gradient sidebar and dark content area
+- Retro
+  - Learn: the default of the old Learn theme, coming with signature light purple, dark sidebar and light content area
+  - Blue: a blue variant of the old Learn theme, coming tinted in blue, dark sidebar and light content area
+  - Green: a green variant of the old Learn theme, coming tinted in green, dark sidebar and light content area
+  - Red: a red variant of the old Learn theme, coming tinted in red, dark sidebar and light content area
+
+## Changing the Variant
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set the `themeVariant` option to change the variant.
+
+The theme offers the recommended [advanced configuration mode](#theme-variant-advanced) that combines the functionality for [multiple variants](#multiple-variants), [OS setting adjustments](#adjust-to-os-settings), and more.
+
+### Simple Setup {#theme-variant}
+
+#### Single Variant
+
+Set `themeVariant` to your theme CSS file name:
+
+{{< multiconfig file=hugo >}}
+[params]
+  themeVariant = 'relearn-light'
+{{< /multiconfig >}}
+
+Place your theme file in `assets/css` or `themes/hugo-theme-relearn/assets/css`. Name it `theme-*.css`.
+
+In the above example, the path of your theme file must be `assets/css/theme-relearn-light.css` or `themes/hugo-theme-relearn/assets/css/theme-relearn-light.css`.
+
+#### Multiple Variants
+
+To let the reader choose between multiple variants, set `themeVariant` like this:
+
+{{< multiconfig file=hugo >}}
+[params]
+  themeVariant = [ 'relearn-light', 'relearn-dark' ]
+{{< /multiconfig >}}
+
+The first variant is the default, and a selector will appear if there's more than one.
+
+#### Adjust to OS Settings
+
+Use the `auto` value to match OS light/dark settings. Usually it makes sense to set it in the first position and make it the default.
+
+{{< multiconfig file=hugo >}}
+[params]
+  themeVariant = [ 'auto', 'red' ]
+{{< /multiconfig >}}
+
+If you don't configure anything else, the theme will default to use `relearn-light` for light mode and `relearn-dark` for dark mode.
+
+Default is `relearn-light` for light and `relearn-dark` for dark mode. These defaults are overwritten by the first two non-auto options of your `themeVariant` array.
+
+You can override the default with `themeVariantAuto`:
+
+{{< multiconfig file=hugo >}}
+[params]
+  themeVariantAuto = [ 'learn', 'neon' ]
+{{< /multiconfig >}}
+
+### Advanced {#theme-variant-advanced}
+
+The theme offers an advanced way to configure theme variants and all of the aspects above inside of a single configuration item. This comes with some features previously unsupported.
+
+Like with the [multiple variants](#multiple-variants) option, you are defining your theme variants in an array but now in a table with suboptions.
+
+Again, in this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer if the array contains more than one entry.
+
+{{< multiconfig file=hugo >}}
+[params]
+  themeVariant = [ 'relearn-light', 'relearn-dark' ]
+{{< /multiconfig >}}
+
+you now write it that way:
+
+{{< multiconfig file=hugo >}}
+[params]
+  [[params.themeVariant]]
+    identifier = 'relearn-light'
+  [[params.themeVariant]]
+    identifier = 'relearn-dark'
+{{< /multiconfig >}}
+
+The `identifier` option is mandatory and equivalent to the string in the first example. Further options can be configured, see the table below.
+
+#### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| identifier            | _&lt;empty&gt;_ | Must correspond to the name of a color variant either in your site's or the theme's directory in the form `assets/css/theme-<IDENTIFIER>.css`. |
+| 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                  | _&lt;empty&gt;_ | 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
+
+{{< multiconfig file=hugo >}}
+[params]
+themeVariant = [
+	{ identifier = 'relearn-auto',  name = 'Relearn Light/Dark', auto = [] },
+	{ identifier = 'relearn-light'  },
+	{ identifier = 'relearn-dark'   },
+	{ identifier = 'relearn-bright' },
+	{ identifier = 'zen-auto',      name = 'Zen Light/Dark', auto = [ 'zen-light', 'zen-dark' ] },
+	{ identifier = 'zen-light'      },
+	{ identifier = 'zen-dark'       },
+	{ identifier = 'retro-auto',    name = 'Retro Learn/Neon', auto = [ 'learn', 'neon' ] },
+	{ identifier = 'neon'           },
+	{ identifier = 'learn'          }
+]
+{{< /multiconfig >}}
+
+## Advanced Topics
+
+### Modifying Variants
+
+In case you like a shipped variant but only want to tweak some aspects, you have some choices. **Don't edit the file in the theme's directory!** You will lose the ability to later easily upgrade your theme to a newer version.
+
+1. Copy and change
+
+    You can copy the shipped variant file from the theme's `themes/hugo-theme-relearn/assets/css` directory to the site's `assets/css` directory and either store it with the same name or give it a new name. Edit the settings and save the new file. Afterwards, you can use it in your `hugo.toml` by the chosen name.
+
+2. Create and import
+
+    You can create a new variant file in the site's `assets/css` directory and give it a new name. Import the shipped variant, add the settings you want to change and save the new file. Afterwards, you can use it in your `hugo.toml` by the chosen name.
+
+    For example, you want to use the `relearn-light` variant but want to change the syntax highlighting schema to the one used in the `neon` variant. For that, create a new `assets/css/theme-my-branding.css` in your site's directory and add the following lines:
+
+    ````css {title="assets/css/theme-my-branding.css"}
+    @import "theme-relearn-light.css";
+
+    :root {
+      --CODE-theme: neon; /* name of the chroma stylesheet file */
+      --CODE-BLOCK-color: rgba( 226, 228, 229, 1 ); /* fallback color for code text */
+      --CODE-BLOCK-BG-color: rgba( 40, 42, 54, 1 ); /* fallback color for code background */
+    }
+    ````
+
+    Afterwards, put this in your `hugo.toml` to use your new variant:
+
+    {{< multiconfig file=hugo >}}
+    [params]
+      themeVariant = 'my-branding'
+    {{< /multiconfig >}}
+
+    In comparison to _copy and change_, this has the advantage that you profit from any adjustments to the `relearn-light` variant while keeping your modifications.
+
+### React to Variant Switches in JavaScript
+
+Once a color variant is fully loaded, either initially or by switching the color variant manually with the variant selector, the custom event `themeVariantLoaded` on the `document` will be dispatched. You can add an event listener and react to changes.
+
+````javascript {title="JavaScript"}
+document.addEventListener( 'themeVariantLoaded', function( e ){
+  console.log( e.detail.variant ); // `relearn-light`
+});
+````

docs/content/configuration/branding/colors/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["explanation", "howto"]
+description = "Learn how to customize your site's colors"
+options = ["themeVariant"]
+title = "Brrrand'n"
+weight = 2
++++
+{{< piratify >}}

docs/content/configuration/branding/generator/_index.en.md

@@ -0,0 +1,29 @@
++++
+categories = ["tutorial"]
+description = "An interactive tool to generate color variant stylesheets"
+options = ["themeVariant"]
+title = "Stylesheet Generator"
+weight = 4
++++
+
+This interactive tool may help you to generate your own color variant stylesheet.
+
+{{% expand "Show usage instructions" %}}
+To get started, first select a color variant from the variant selector in the lower left sidebar that fits you best as a starting point.
+
+The graph is interactive and reflects the current colors. You can click on any of the colored boxes to adjust the respective color. The graph **and the page** will update accordingly.
+
+The arrowed lines reflect how colors are inherited through different parts of the theme if the descendant isn't overwritten. If you want to delete a color and let it inherit from its parent, just delete the value from the input field.
+
+To better understand this, select the `neon` variant and modify the different heading colors. There, colors for the headings `h2`, `h3` and `h4` are explicitly set. `h5` is not set and inherits its value from `h4`. `h6` is also not set and inherits its value from `h5`.
+
+Once you've changed a color, the variant selector will show a "My custom variant" entry and your changes are stored in the browser. You can **browse to other pages** and even close the browser **without losing your changes**.
+
+Once you are satisfied, you can download the new variants file and copy it into your site's `assets/css` directory.
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Afterwards, you have to adjust the `themeVariant` option in your `hugo.toml` to your chosen file name. For example, if your new variants file is named `theme-my-custom-variant.css`, you have to set `themeVariant='my-custom-variant'` to use it.
+
+See the docs for [further configuration options](configuration/branding/colors).
+{{% /expand %}}
+
+{{% variantgenerator %}}

docs/content/configuration/branding/generator/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["tutorial"]
+description = "An interactive tool to generate color variant stylesheets"
+options = ["themeVariant"]
+title = "Stylesheet Generrrat'r"
+weight = 4
++++
+{{< piratify >}}

docs/content/configuration/branding/logo/_index.en.md

@@ -0,0 +1,41 @@
++++
+categories = ["howto"]
+description = "Provide your own logo and favicon"
+title = "Logo"
+weight = 1
++++
+
+## Change the Favicon
+
+If your favicon is an SVG, PNG, or ICO, just drop your image in your site's `static/images/` directory and name it `favicon.svg`, `favicon.png`, or `favicon.ico` respectively.
+
+If you want to adjust your favicon according to your OS settings for light/dark mode, add the image files `static/images/favicon-light.svg` and `static/images/favicon-dark.svg` to your site's directory, respectively, corresponding to your file format. In case some of the files are missing, the theme falls back to `favicon.svg` for each missing file. All supplied favicons must be of the same file format.
+
+If no favicon file is found, the theme will look up the alternative filename `logo` in the same location and will repeat the search for the list of supported file types.
+
+If you need to change this default behavior, create a new file `layouts/partials/favicon.html` in your site's directory and write something like this:
+
+````html {title="layouts/partials/favicon.html"}
+<link rel="icon" href="/images/favicon.bmp" type="image/bmp">
+````
+
+## Change the Logo
+
+By default, only your site title will be shown at the top of the menu. You can [configure this](configuration/sidebar/headerfooter#title), or override the logo partial.
+
+Create a new file in `layouts/partials/logo.html` of your site. Then write any HTML you want. You could use an `img` HTML tag and reference an image, or you could paste an SVG definition!
+
+The size of the logo will adapt automatically.
+
+> [!note]
+> In case of SVGs, additional styling may be required.
+
+### Example
+
+Suppose you've stored your logo as `static/images/logo.png` then your `layouts/partials/logo.html` could look something like this:
+
+````html {title="layouts/partials/logo.html"}
+<a id="R-logo" href="{{ partial "permalink.gotmpl" (dict "to" .Site.Home) }}">
+  <img src="{{"images/logo.png" | relURL}}" alt="brand logo">
+</a>
+````

docs/content/configuration/branding/logo/_index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["howto"]
+description = "Provide your own logo and favicon"
+title = "Logo"
+weight = 1
++++
+{{< piratify >}}

docs/content/configuration/branding/modules/_index.en.md

@@ -0,0 +1,36 @@
++++
+categories = ["howto"]
+description = "Colors of syntax highlighting and 3rd-party modules"
+title = "Module Theming"
+weight = 3
++++
+
+## Change Syntax Highlighting
+
+If you want to switch the syntax highlighting theme together with your color variant, first you need to configure your installation [according to Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/#generate-syntax-highlighter-css) to provide a syntax highlighting stylesheet file.
+
+{{< multiconfig file=hugo >}}
+markup.highlight.noClasses=false
+{{< /multiconfig >}}
+
+You can use one of the shipped stylesheet files or use Hugo to generate a file for you.
+
+````shell
+hugo gen chromastyles --style=monokai > chroma-mycode.css
+````
+
+The file must be written to `assets/css/chroma-<NAME>.css`. To use it with your color variant, you have to modify `--CODE-theme: <NAME>` in the color variant stylesheet file.
+
+````css {title="assets/css/theme-my-branding.css"}
+@import "theme-relearn-light.css";
+:root {
+  --CODE-theme: mycode; /* name of the chroma stylesheet file */
+}
+````
+
+## Change 3rd-Party Libraries Theming
+
+Some of the shipped shortcodes are using 3rd-party libraries. See the individual shortcode documentation on how to change their theming.
+
+- [`mermaid` shortcode](shortcodes/mermaid#setting-a-specific-mermaid-theme)
+- [`openapi` shortcode](shortcodes/openapi#setting-a-specific-swagger-ui-theme)

docs/content/configuration/branding/modules/_index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["howto"]
+description = "Colors of syntax highlighting and 3rd-party modules"
+title = "Module Theming"
+weight = 3
++++
+{{< piratify >}}

docs/content/configuration/content/_index.en.md

@@ -0,0 +1,9 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Configure the content area of your site"
+title = "Content"
+weight = 4
++++
+
+{{% children containerstyle="div" style="h2" description=true %}}

docs/content/configuration/content/_index.pir.md

@@ -0,0 +1,8 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Configure the content area of your site"
+title = "Content"
+weight = 4
++++
+{{< piratify >}}

docs/content/configuration/content/headings/index.en.md

@@ -0,0 +1,29 @@
++++
+categories = ["howto"]
+description = "Configuring heading anchors"
+options = ["disableAnchorCopy", "disableAnchorScrolling"]
+title = "Headings"
+weight = 3
++++
+
+Headings can have anchor links that appear when you hover over them.
+
+You can change what happens when you click the anchor icon in your `hugo.toml` file. By default, all options are turned on. If you turn off all options, no anchor icon will show up when you hover.
+
+## Copy Anchor Links
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `disableAnchorCopy=true` to prevent copying the anchor link when you click the icon.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableAnchorCopy = true
+{{< /multiconfig >}}
+
+## Scroll to Heading
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `disableAnchorScrolling=true` to stop the page from scrolling to the heading when you click the anchor icon.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableAnchorScrolling = true
+{{< /multiconfig >}}

docs/content/configuration/content/headings/index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["howto"]
+description = "Configuring heading anchors"
+options = ["disableAnchorCopy", "disableAnchorScrolling"]
+title = "Headings"
+weight = 3
++++
+{{< piratify >}}

docs/content/configuration/content/hidden/_index.en.md

@@ -0,0 +1,44 @@
++++
+categories = ["explanation", "howto"]
+description = "Learn about the hidden pages feature"
+options = ["disableSearchHiddenPages", "disableSeoHiddenPages", "disableTagHiddenPages"]
+title = "Hidden Pages"
+weight = 5
++++
+
+This theme allows you to [create hidden pages](authoring/meta#hidden).
+
+Hidden pages are created but not shown in the navigation. This is useful for pages you only want to access via a direct link.
+
+When you visit a hidden page's URL, it will appear in the navigation menu.
+
+Hidden pages can also have hidden subpages, creating multiple levels of hiding.
+
+By default, hidden pages are only hidden from human visitors. Search engines can still find them by crawling your site and the pages are linked in your taxonomies and site search. You can prevent this with these options.
+
+## Hide from Search
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} To remove hidden pages from search results, use `disableSearchHiddenPages=true`.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableSearchHiddenPages = true
+{{< /multiconfig >}}
+
+## Hide from Search Engines
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} To hide pages from search engines by removing them from the sitemap, RSS feed and [make them `nofollow`](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag#directives), use `disableSeoHiddenPages=true`.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableSeoHiddenPages = true
+{{< /multiconfig >}}
+
+## Hide from Taxonomies
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} To prevent hidden pages from appearing on taxonomy and term pages, use `disableTagHiddenPages=true`. If this makes a term's count zero, an empty term page will still be created but not linked.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableTagHiddenPages = true
+{{< /multiconfig >}}

docs/content/configuration/content/hidden/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["explanation", "howto"]
+description = "Learn about the hidden pages feature"
+options = ["disableSearchHiddenPages", "disableSeoHiddenPages", "disableTagHiddenPages"]
+title = "Hidden Pages"
+weight = 5
++++
+{{< piratify >}}

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

@@ -0,0 +1,35 @@
++++
+categories = ["howto"]
+description = "What options are available for links and images"
+options = ["disableDefaultRelref", "disableExplicitIndexURLs"]
+title = "Linking"
+weight = 4
++++
+
+Further [settings are available](authoring/frontmatter/linking) to be used in your configuration or front matter.
+
+## URL Management
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, the theme adds `index.html` to page links when `uglyURLs=false` (Hugo's default).
+
+If you're only using a web server scenario and dislike this, you can reset to Hugo's default behavior by settings `disableExplicitIndexURLs=true`.
+
+For the file system scenario, you are not allowed to change this value.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableExplicitIndexURLs = true
+{{< /multiconfig >}}
+
+## Patching the `relref` Shortcode
+
+{{% 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 is failing.
+
+To work around this, you can activate a patched version of the shortcode by setting `disableDefaultRelref=true`.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableDefaultRelref = true
+{{< /multiconfig >}}

docs/content/configuration/content/linking/index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["howto"]
+description = "What options are available for links and images"
+options = ["disableDefaultRelref", "disableExplicitIndexURLs"]
+title = "Linking"
+weight = 4
++++
+{{< piratify >}}

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

@@ -0,0 +1,33 @@
++++
+categories = ["howto"]
+description = "Configuring titles and breadcrumbs to your needs"
+options = ["breadcrumbSeparator", "disableRootBreadcrumb", "disableTermBreadcrumbs", "titleSeparator"]
+title = "Titles & Breadcrumbs"
+weight = 2
++++
+
+## Breadcrumbs
+
+Learn how to turn off the breadcrumbs completely and further [configure the topbar](authoring/frontmatter/topbar).
+
+{{% 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 %}} 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 >}}

docs/content/configuration/content/titles/index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["howto"]
+description = "Configuring titles and breadcrumbs to your needs"
+options = ["breadcrumbSeparator", "disableRootBreadcrumb", "disableTermBreadcrumbs", "titleSeparator"]
+title = "Titles & Breadcrumbs"
+weight = 2
++++
+{{< piratify >}}

docs/content/configuration/content/width/_index.en.md

@@ -0,0 +1,24 @@
++++
+categories = ["howto"]
+description = "Changing the content area width"
+title = "Width"
+weight = 1
++++
+
+The theme adjusts the content width when you resize your browser.
+
+If you want to change the chosen default width, you can add CSS variables to `layouts/partials/custom-header.html`.
+
+## Changing the Main Area's Maximum Width
+
+The main area has a default maximum width of `80.25rem` for better readability. If you want to change this, you can set a CSS variable
+
+For full width, use a large value like `1000rem`.
+
+````html {title="layouts/partials/custom-header.html"}
+<style>
+:root {
+    --MAIN-WIDTH-MAX: 1000rem;
+}
+</style>
+````

docs/content/configuration/content/width/_index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["howto"]
+description = "Changing the content area width"
+title = "Width"
+weight = 1
++++
+{{< piratify >}}

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

@@ -0,0 +1,9 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Customize files for advanced usage"
+title = "Customization"
+weight = 5
++++
+
+{{% children containerstyle="div" style="h2" description=true %}}

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

@@ -0,0 +1,8 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Customize files for advanced usage"
+title = "Customization"
+weight = 5
++++
+{{< piratify >}}

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

@@ -0,0 +1,148 @@
++++
+categories = ["explanation", "howto"]
+description = "Extending page designs"
+title = "Page Designs"
+weight = 5
++++
+
+Page designs are used to provide different layouts for a given output format. If you instead want to [provide a new output format](configuration/customization/outputformats), the theme got you covered as well.
+
+A page is displayed by exactly one page design _for each output format_, is represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type) and uses [Hugo's content view mechanism](https://gohugo.io/templates/types/#content-view).
+
+A page design usually consists of
+
+- [one or more content view files](https://gohugo.io/templates/types/#content-view): depending on the output format taken from [the list below](#partials)
+- [an optional archetype file](https://gohugo.io/content-management/archetypes/): a template for creating new Markdown files with the correct setting for the `type` front matter and any furhter parameter
+- optional CSS styles
+
+> [!warning]
+> Don't use Hugo's reserved `type` option in your modifications for other functionality!
+
+## Using a Page Design
+
+Regardless of shipped or custom page designs, you are [using them in the same way](authoring/frontmatter/designs). Either by manually setting the `type` front matter to the value of the page design or by using an archetype during creation of a new page.
+
+If no `type` is set in your front matter or the page design doesn't exist for a given output format, the page is treated as if `type='default'` was set.
+
+The Relearn theme ships with the page designs `home`, `chapter`, and `default` for the HTML output format.
+
+The shipped `print` and `markdown` output formats only display using the `default` page design.
+
+## Creating a Page Design
+
+Suppose you are writing a documentation site for some software. Each time a new release is created, you are adding a new releasenotes page to your site. Those pages should contain a common disclaimer at the top. You neither want to copy the text into each new file nor want you to use a shortcode but create a page design called `releasenotes`.
+
+1. Choose a name (here, `releasenotes`)
+2. Create a content view file at `layouts/releasenotes/views/article.html`
+
+    ````html {title="layouts/releasenotes/views/article.html" hl_Lines="6-8"}
+    <article class="releasenotes">
+      <header class="headline">
+        {{partial "content-header.html" .}}
+      </header>
+      {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}
+      <p class="disclaimer">
+        This software release comes without any warranty!
+      </p>
+      {{partial "article-content.html" .}}
+      <footer class="footline">
+        {{partial "content-footer.html" .}}
+      </footer>
+    </article>
+    ````
+
+    The marked lines are your customizations, the rest of the file was copied over from the default implementation of [`layouts/_default/views/article.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/article.html)
+
+    In this file, you can customize the page structure as needed. For HTML based output formats, typically you'll want to:
+
+    - Set a `class` at the `article` element for custom CSS styles
+    - Call `{{ partial "article-content.html" . }}` to show your page content
+
+3. _Optional_: create an archetype file at `archetypes/releasenotes.md`
+
+    ````toml {title="archetypes/releasenotes.md"}
+    +++
+    title = "{{ replace .Name "-" " " | title }}"
+    type = "releasenotes"
+    +++
+
+    This is a new releasenote.
+    ````
+
+4. _Optional_: add CSS in the file `layouts/partials/custom-header.html`
+
+    ````html {title="layouts/partials/custom-header.html"}
+    <style>
+    .releasenotes .disclaimer {
+      background-color: pink;
+      font-size: 72rem;
+    }
+    </style>
+    ````
+
+## Partials
+
+### For any Output Format
+
+These files are common for all output formats.
+
+- `layouts/<DESIGN>/baseof.<FORMAT>`: _Optional_: The top most file you could provide to completely redefine the whole design. No further partials will be called if you don' call them yourself
+
+### For HTML Output Formats
+
+If you want to keep the general HTML framework and only change specific parts, you can provide these files for the page desingn for the HTML output format independently of one another.
+
+- `layouts/<DESIGN>/views/article.html`: _Optional_: Controls how one page's content and title are displayed
+- `layouts/<DESIGN>/views/body.html`: _Optional_: Determines what to contain in the content area (for example a single page, a list of pages, a tree of sub pages)
+- `layouts/<DESIGN>/views/menu.html`: _Optional_: Defines the sidebar menu layout
+
+For a real-world example, check out the `changelog` page design implementation
+
+- [`docs/layouts/changelog/views/article.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/docs/layouts/changelog/views/article.html)
+
+## Migration to Relearn 7 or higher
+
+Previous to Relearn 7, page designs were defined by a proprietary solution unique to the theme. Depending on your modifications you may have to change some or all of the following to migrate to Relearn 7's page designs.
+
+- In all your `*.md` files, replace the `archetype` front matter with `type`; the value stays the same; don't forget your archetype files if you have some
+- Move your files `layouts/partials/archetypes/<DESIGN>/article.html` to `layouts/<DESIGN>/views/article.html`
+
+    The files will most likely require further modifications as they now receive the page as it context (dot `.`) instead of the `.page` and `.content` parameter.
+
+    **Old**:
+
+    ````html {title="layouts/partials/archetypes/&lt;DESIGN&gt;/article.html" hl_Lines="1-3 10 16"}
+    {{- $page := .page }}
+    {{- $content := .content }}
+    {{- with $page }}
+    <article class="default">
+      <header class="headline">
+        {{- partial "content-header.html" . }}
+      </header>
+      {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}
+
+      {{ $content | safeHTML }}
+
+      <footer class="footline">
+        {{- partial "content-footer.html" . }}
+      </footer>
+    </article>
+    {{- end }}
+    ````
+
+    **New**:
+
+    ````html {title="layouts/&lt;DESIGN&gt;/views/article.html" hl_Lines="7"}
+    <article class="default">
+      <header class="headline">
+        {{- partial "content-header.html" . }}
+      </header>
+      {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}
+
+      {{ partial "article-content.html" . }}
+
+      <footer class="footline">
+        {{- partial "content-footer.html" . }}
+      </footer>
+    </article>
+    ````

docs/content/configuration/customization/designs/index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["explanation", "howto"]
+description = "Using and extending page designs"
+title = "Page Designs"
+weight = 5
++++
+{{< piratify >}}

docs/content/configuration/customization/extending/_index.en.md

@@ -0,0 +1,63 @@
++++
+categories = ["explanation", "howto"]
+description = "Add further code to your site"
+options = ["relearn.dependencies"]
+title = "Extending Scripts"
+weight = 2
++++
+
+A common question is how to add extra CSS styles or JavaScript to your site. This depends on what you need.
+
+## Adding JavaScript or Stylesheets to All Pages
+
+To add JavaScript files or CSS stylesheets to every page, you can include them in `layouts/partials/custom-header.html` or `layouts/partials/custom-footer.html`.
+
+However, this can make your site larger than necessary if these files are only needed on a few pages. The next section explains how to add dependencies only when needed.
+
+## Custom Shortcodes with Dependencies
+
+Some shortcodes need extra JavaScript and CSS files. The theme only loads these when the shortcode is used. You can use this for your own shortcodes too.
+
+For example, to create a shortcode called `myshortcode` that needs the `jquery` library:
+
+1. Create the shortcode file `layouts/shortcodes/myshortcode.html` and add the folloging line somewhere:
+
+    ````go {title="layouts/shortcodes/myshortcode.html"}
+    ...
+    {{- .Page.Store.Set "hasMyShortcode" true }}
+    ...
+    ````
+
+2. {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Add this to your `hugo.toml`:
+
+    {{< multiconfig file=hugo >}}
+    [params.relearn.dependencies]
+      [params.relearn.dependencies.myshortcode]
+        name = 'MyShortcode'
+    {{< /multiconfig >}}
+
+3. Create loader file `layouts/partials/dependencies/myshortcode.html`:
+
+    ````go {title="layouts/partials/dependencies/myshortcode.html"}
+    {{- if eq .location "footer" }}
+      <script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>
+    {{- end }}
+    ````
+
+Important notes:
+
+- Character casing is relevant!
+- The `name` in `hugo.toml` must match the `Store` key used in the shortcode file, prefixed with a `has`.
+- The key of `relearn.dependencies` must match the loader file name.
+
+See the `math`, `mermaid`, and `openapi` shortcodes for examples.
+
+{{% notice note %}}
+For advanced customization, you can use the dependency loader in your own partials:
+
+````go
+{{- partial "dependencies.gotmpl" (dict "page" . "location" "mylocation") }}
+````
+{{% /notice %}}
+
+Give a unique name for the `location` parameter when you call it, so you can distinguish your loaders behavior depending on the location it was called from.

docs/content/configuration/customization/extending/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["explanation", "howto"]
+description = "Add further code to your site"
+options = ["relearn.dependencies"]
+title = "Extending Scripts"
+weight = 2
++++
+{{< piratify >}}

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

@@ -0,0 +1,82 @@
++++
+categories = ["explanation", "howto"]
+description = "How to extend image effects"
+options = ["imageEffects"]
+title = "Image Effects"
+weight = 3
++++
+
+This page shows you, how to configure custom [image effects](authoring/markdown#image-effects) on top of existing ones.
+
+This setting can also [be overridden by your front matter](authoring/imageeffects).
+
+If you don't configure anything in your `hugo.toml`, the image effects default to
+
+## Default Values
+
+{{< multiconfig >}}
+[imageEffects]
+  border = false
+  lazy = true
+  lightbox = true
+  shadow = false
+{{< /multiconfig >}}
+
+## 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]
+  bg-white = true
+  border = true
+  lazy = false
+  lightbox = true
+  shadow = false
+{{< /multiconfig >}}
+
+### Example
+
+With this configuration in effect, the following URL
+
+````markdown {title="Markdown"}
+![Minion](https://octodex.github.com/images/minion.png)
+````
+
+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">
+````
+
+## Styling Effects
+
+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>
+img.bg-white {
+  background-color: white;
+}
+img.nobg-white {
+  background-color: transparent;
+}
+</style>
+````

docs/content/configuration/customization/imageeffects.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["explanation", "howto"]
+description = "How to extend image effects"
+options = ["imageEffects"]
+title = "Image Effects"
+weight = 3
++++
+{{< piratify >}}

docs/content/configuration/customization/outputformats/_index.en.md

@@ -0,0 +1,229 @@
++++
+categories = ["explanation", "howto"]
+description = "Adding Custom Output Formats"
+title = "Output Formats"
+weight = 6
+disableToc = false
++++
+
+Hugo can display your content in different [formats](https://gohugo.io/templates/output-formats/) like HTML, JSON, Google AMP, etc. To do this, templates must be provided.
+
+The Relearn theme by default comes with templates for [HTML, HTML for print, RSS and Markdown](configuration/sitemanagement/outputformats). If this is not enough, this page describes how you can create your own output formats.
+
+If you instead just want to [customize the layout of an existing output format](configuration/customization/designs), the theme got you covered as well.
+
+## Creating an Output Format
+
+Suppose you want to be able to send your articles as HTML formatted emails. The pages of these format need to be self contained so an email client can display the content without loading any further assets.
+
+Therefore we add a new output format called `email` that outputs HTML and assembles a completely custom HTML document structure.
+
+1. Add the output format to your `hugo.toml`
+
+    {{< multiconfig file=hugo >}}
+    [outputFormats]
+      [outputFormats.email]
+        name= "email"
+        baseName = "index.email"
+        isHTML = true
+        mediaType = 'text/html'
+        permalinkable = false
+        noUgly = true
+
+    [outputs]
+      home = ["html", "rss", "email"]
+      section = ["html", "rss", "email"]
+      page = ["html", "rss", "email"]
+    {{< /multiconfig >}}
+
+2. Create a file `layouts/_default/baseof.email.html`
+
+    ````html {title="layouts/_default/baseof.email.html" hl_Lines="15"}
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>{{ .Title }}</title>
+      <style type="text/css">
+        /* add some styles here to make it pretty */
+      </style>
+      <style type="text/css">
+        /* add chroma style for code highlighting */
+        {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
+      </style>
+    </head>
+    <body>
+      <main>
+        {{- block "body" . }}{{ end }}
+      </main>
+    </body>
+    </html>
+    ````
+
+    The marked `block` construct above will cause the display of the article with a default HTML structure. 	In case you want to keep it really simple, you could replace this line with just `{{ .Content }}`.
+
+3. _Optional_: create a file `layouts/_default/views/article.email.html`
+
+	In our case, we want to display a disclaimer in front of every article. To do this we have to define the output of an article ourself and rely on the above `block` statement to call our template.
+
+    ````html {title="layouts/_default/views/article.email.html"}
+    <article class="email">
+      <blockquote>
+        View this article on <a href="http://example.com{{ .RelPermalink }}">our website</a>
+      </blockquote>
+      {{ partial "article-content.html" . }}
+    </article>
+    ````
+
+4. _Optional_: create a file `layouts/_default/_markup_/render-image.email.html`
+
+    In our case, we want to convert each image into a base 64 encoded string to display it inline in the email without loading external assets.
+
+    ````html {title="layouts/_default/_markup_/render-image.email.html"}
+    {{- $dest_url := urls.Parse .Destination }}
+    {{- $dest_path := path.Clean ($dest_url.Path) }}
+    {{- $img := .Page.Resources.GetMatch $dest_path }}
+    {{- if and (not $img) .Page.File }}
+      {{- $path := path.Join .Page.File.Dir $dest_path }}
+      {{- $img = resources.Get $path }}
+    {{- end }}
+    {{- if $img }}
+      {{- if (gt (len $img.Content) 1000000000) }}
+        {{/* currently resizing does not work for animated gifs :-( */}}
+        {{- $img = $img.Resize "600x webp q75" }}
+      {{- end }}
+      <img src="data:{{ $img.MediaType }};base64,{{ $img.Content | base64Encode }}">
+    {{- end }}
+    ````
+
+## Partials
+
+### For HTML Output Formats
+
+If you want to keep the general HTML framework and only change specific parts, you can provide these files for your output format independently of one another:
+
+- `layouts/_default/views/article.<FORMAT>.html`: _Optional_: Controls how a page's content and title are displayed
+- `layouts/_default/views/body.<FORMAT>.html`: _Optional_: Determines what to contain in the content area (for example a single page, a list of pages, a tree of sub pages)
+- `layouts/_default/views/menu.<FORMAT>.html`: _Optional_: Defines the sidebar menu layout
+- `layouts/_default/views/storeOutputFormat.<FORMAT>.html`: _Optional_: Stores the output format name for use in the framework to let the body element been marked with an output format specific class
+
+For a real-world example, check out the `print` output format implementation
+
+- [`layouts/_default/views/body.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/body.print.html)
+- [`layouts/_default/views/menu.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/menu.print.html)
+- [`layouts/_default/views/storeOutputFormat.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/storeOutputFormat.print.html)
+
+### For Non-HTML Output Formats
+
+- `layouts/_default/list.<FORMAT>`: _Mandatory_: Controls how sections are displayed
+- `layouts/_default/single.<FORMAT>`: _Mandatory_: Controls how pages are displayed
+- `layouts/_default/baseof.<FORMAT>`: _Optional_: Controls how sections and pages are displayed. If not provided, you have to provide your implementation in `list.<FORMAT>` and `single.<FORMAT>`
+
+For a real-world example, check out the `markdown` output format implementation
+
+- [`layouts/_default/baseof.md`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/baseof.md)
+- [`layouts/_default/list.md`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/list.md)
+- [`layouts/_default/single.md`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/single.md)
+
+## Migration to Relearn 7 or higher
+
+Previous to Relearn 7, HTML output formats did not use the `baseof.html` but now do.
+
+### For HTML Output Formats
+
+- Move your files `layouts/partials/article.<FORMAT>.html` to `layouts/_default/views/article.<FORMAT>.html`
+
+    The files will most likely require further modifications as they now receive the page as it context (dot `.`) instead of the `.page` and `.content` parameter.
+
+	**Old**:
+
+    ````html {title="layouts/partials/article.&lt;FORMAT&gt;.html" hl_Lines="1-3 10 16"}
+    {{- $page := .page }}
+    {{- $content := .content }}
+    {{- with $page }}
+    <article class="default">
+      <header class="headline">
+        {{- partial "content-header.html" . }}
+      </header>
+      {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}
+
+      {{ $content | safeHTML }}
+
+      <footer class="footline">
+        {{- partial "content-footer.html" . }}
+      </footer>
+    </article>
+    {{- end }}
+    ````
+
+	**New**:
+
+    ````html {title="layouts/_default/views/article.&lt;FORMAT&gt;.html" hl_Lines="7"}
+    <article class="default">
+      <header class="headline">
+        {{- partial "content-header.html" . }}
+      </header>
+      {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}
+
+      {{ partial "article-content.html" . }}
+
+      <footer class="footline">
+        {{- partial "content-footer.html" . }}
+      </footer>
+    </article>
+    ````
+
+### For Non-HTML Output Formats
+
+- Merge your files `layouts/partials/header.<FORMAT>.html`, `layouts/partials/footer.<FORMAT>.html` to `layouts/_default/baseof.<FORMAT>.html`
+
+	**Old**:
+
+    ````html {title="layouts/partials/header.&lt;FORMAT&gt;.html"}
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>{{ .Title }}</title>
+      <style type="text/css">
+        /* add some styles here to make it pretty */
+      </style>
+      <style type="text/css">
+        /* add chroma style for code highlighting */
+        {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
+      </style>
+    </head>
+    <body>
+      <main>
+    ````
+
+    ````html {title="layouts/partials/footer.&lt;FORMAT&gt;.html"}
+      </main>
+    </body>
+    </html>
+    ````
+
+	**New**:
+
+	The upper part of the file is from your `header.<FORMAT>.html` and the lower part is from your `footer.<FORMAT>.html`.
+
+	The marked line needs to be added, so your output format uses a potential `layouts/_default/views/article.<FORMAT>.html`
+
+    ````html {title="layouts/_default/baseof.&lt;FORMAT&gt;.html" hl_Lines="15"}
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>{{ .Title }}</title>
+      <style type="text/css">
+        /* add some styles here to make it pretty */
+      </style>
+      <style type="text/css">
+        /* add chroma style for code highlighting */
+        {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
+      </style>
+    </head>
+    <body>
+      <main>
+        {{- block "body" . }}{{ end }}
+      </main>
+    </body>
+    </html>
+    ````

docs/content/configuration/customization/outputformats/_index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["explanation", "howto"]
+description = "Adding Custom Output Formats"
+title = "Output Formats"
+weight = 6
++++
+{{< piratify >}}

docs/content/configuration/customization/partials/index.en.md

@@ -0,0 +1,46 @@
++++
+categories = ["explanation"]
+description = "Modifying partials to your needs"
+title = "Partials"
+weight = 1
++++
+
+## Usable Partials
+
+You can call other partials from `themes/hugo-relearn-themes/` besides those in `themes/hugo-relearn-themes/layouts/partials/_relearn`. However, using partials not mentioned as customizable below might make future updates more challenging.
+
+## Customizable Partials
+
+The Relearn theme allows you to customize various parts of the theme by overriding partials. This makes the theme highly configurable.
+
+A good rule to follow: The less code a partial contains, the easier it will be to update the theme in the future.
+
+Here's a list of partials you can safely override:
+
+- `layouts/partials/content.html`: The main content of a page. Override this to display additonal page metadata.
+
+- `layouts/partials/content-header.html`: The header above the title. By default, it shows tags, but you can change this.
+
+- `layouts/partials/content-footer.html`: The footer below the content. By default, it shows author info, modification dates, and categories. You can customize this.
+
+- `layouts/partials/custom-header.html`: For adding custom CSS. Remember to include the `style` HTML tag.
+
+- `layouts/partials/custom-footer.html`: For adding custom JavaScript. Remember to include the `script` HTML tag.
+
+- `layouts/partials/favicon.html`: The favicon. You should definitely customize this.
+
+- `layouts/partials/heading.html`: the page's title headings
+
+- `layouts/partials/heading-pre.html`: Add content before the page's title headings. Remember to consider the `headingPre` front matter.
+
+- `layouts/partials/heading-post.html`: Add content after the page's title headings. Remember to consider the `headingPost` front matter.
+
+- `layouts/partials/logo.html`: The logo in the top left corner. You should customize this.
+
+- `layouts/partials/menu-pre.html`: Add content before menu items. Remember to consider the `menuPre` front matter.
+
+- `layouts/partials/menu-post.html`: Add content after menu items. Remember to consider the `menuPost` front matter.
+
+- `layouts/partials/menu-footer.html`: The footer of the left menu.
+
+You can override other partials from `themes/hugo-relearn-themes/`, but be careful as this might make future updates more difficult.

docs/content/configuration/customization/partials/index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["explanation"]
+description = "Modifying partials to your needs"
+title = "Partials"
+weight = 1
++++
+{{< piratify >}}

docs/content/configuration/customization/taxonomy.en.md

@@ -0,0 +1,54 @@
++++
+categories = ["explanation", "howto", "reference"]
+description = "How to display custom taxonomies on your pages"
+tags = ["taxonomy"]
+title = "Taxonomies"
+weight = 7
++++
+
+This page explains how to show custom taxonomies on your pages.
+
+For more details, check the official docs on [setting up custom taxonomies](https://gohugo.io/content-management/taxonomies/#configure-taxonomies) and [using them in your content](https://gohugo.io/content-management/taxonomies/#assign-terms-to-content).
+
+## Default Behavior
+
+The Relearn theme automatically shows Hugo's [default taxonomies](https://gohugo.io/content-management/taxonomies/#default-taxonomies) _tags_ and _categories_ out of the box.
+
+- Tags appear at the top of the page in alphabetical order in form of baggage tags.
+- Categories appear at the bottom of the page in alphabetical order as a list prefixed with an icon.
+
+Each item links to a page showing all articles with that term.
+
+## Setting Up Custom Taxonomies
+
+To add custom taxonomies, update your `hugo.toml` file. You also have to add the default taxonomies if you want to use them.
+
+{{< multiconfig file=hugo >}}
+[taxonomies]
+  category = 'categories'
+  mycustomtag = 'mycustomtags'
+  tag = 'tags'
+{{< /multiconfig >}}
+
+## Showing Custom Taxonomies
+
+To display your custom taxonomy terms, add this to your page (usually in `layouts/partials/content-footer.html`):
+
+````go
+{{ partial "term-list.html" (dict
+  "page" .
+  "taxonomy" "mycustomtags"
+  "icon" "layer-group"
+) }}
+````
+
+### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| **page**              | _&lt;empty&gt;_ | Mandatory reference to the page. |
+| **taxonomy**          | _&lt;empty&gt;_ | The plural name of the taxonomy to display as used in your front matter. |
+| **class**             | _&lt;empty&gt;_ | Additional CSS classes set on the outermost generated HTML element.<br><br>If set to `tags` you will get the visuals for displaying the _tags_ taxonomy, otherwise it will be a simple list of links as for the _categories_ taxonomy. |
+| **style**             | `primary`       | The style scheme used if **class** is `tags`.<br><br>- by severity: `caution`, `important`, `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`, `accent`<br>- by color: `blue`, `cyan`, `green`, `grey`, `magenta`, `orange`, `red`<br>- by special color: `default`, `transparent`, `code` |
+| **color**             | see notes       | The [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to be used if **class** is `tags`. If not set, the chosen color depends on the **style**. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching color for the severity<br>- for all other styles: the corresponding color |
+| **icon**              | _&lt;empty&gt;_ | An optional [Font Awesome icon name](shortcodes/icon#finding-an-icon) set to the left of the list. |

docs/content/configuration/customization/taxonomy.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["explanation", "howto", "reference"]
+description = "How to display custom taxonomies on your pages"
+tags = ["taxonomy"]
+title = "Taxonomies"
+weight = 7
++++
+{{< piratify >}}

docs/content/configuration/customization/topbar/_index.en.md

@@ -0,0 +1,182 @@
++++
+categories = ["explanation", "reference"]
+description = "How to extend the topbar"
+options = ["editURL"]
+outputs = ["html", "rss", "print", "markdown", "source"]
+title = "Topbar"
+weight = 4
++++
+
+The theme comes with a reasonably configured topbar. You can learn how to [configure the defaults in this section](authoring/frontmatter/topbar).
+
+![topbar on mobile devices](topbar-closed.png)
+
+Nevertheless, your requirements may differ from this configuration. Luckily, the theme has you covered as the topbar, its buttons, and the functionality behind these buttons are fully configurable by you.
+
+{{% notice tip %}}
+All mentioned file names below can be clicked and show you the implementation for a better understanding.
+{{% /notice %}}
+
+## Areas
+
+The default configuration comes with three predefined areas that may contain an arbitrary set of buttons.
+
+![topbar with default areas marked](topbar-areas.png)
+
+- [**start**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/area/start.html): shown between menu and breadcrumb
+- [**end**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/area/end.html): shown on the opposite breadcrumb side in comparison to the _start_ area
+- [**more**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/area/more.html): shown when pressing the {{% button style="transparent" icon="ellipsis-v" %}}{{% /button %}} _more_ button in the topbar
+
+While you cannot add additional areas in the topbar, you are free to configure additional buttons that behave like the _more_ button, providing further user-defined areas.
+
+## Buttons
+
+The theme ships with the following predefined buttons (from left to right in the screenshot):
+
+- {{% button style="transparent" icon="bars" %}}{{% /button %}} [**sidebar**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/sidebar.html): opens the sidebar flyout if in mobile layout
+- {{% button style="transparent" icon="list-alt" %}}{{% /button %}} [**toc**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/toc.html): [opens the table of contents in an overlay](authoring/frontmatter/topbar#table-of-contents)
+- {{% button style="transparent" icon="pen" %}}{{% /button %}} [**edit**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/edit.html): browses to the editable page if the `editURL` [parameter is set](authoring/frontmatter/topbar#edit-button)
+- {{% button style="transparent" icon="file-code" %}}{{% /button %}} **source**: [**source**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/markdown.html): browses to the chapter's source code if [markdown support](configuration/sitemanagement/outputformats#source-support) was activated
+- {{% button style="transparent" icon="fa-fw fab fa-markdown" %}}{{% /button %}} [**markdown**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/markdown.html): browses to the chapter's markdown source if [markdown support](configuration/sitemanagement/outputformats#markdown-support) was activated
+- {{% button style="transparent" icon="print" %}}{{% /button %}} [**print**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/print.html): browses to the chapter's printable page if [print support](configuration/sitemanagement/outputformats#print-support) was activated
+- {{% button style="transparent" icon="chevron-left" %}}{{% /button %}} [**prev**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/prev.html): browses to the [previous page](authoring/frontmatter/topbar#arrow-navigation) if there is one
+- {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} [**next**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/next.html): browses to the [next page]authoring/frontmatter/topbar(#arrow-navigation) if there is one
+- {{% button style="transparent" icon="ellipsis-v" %}}{{% /button %}} [**more**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/more.html): opens the overlay for the _more_ area
+
+Not all buttons are displayed at every given time. This is configurable (see below if interested).
+
+## Redefining Areas
+
+Each predefined area and button comes in its own file. By that, it is easy for you to overwrite an area file in your installation, reusing only the buttons you like.
+
+E.g., you can redefine the predefined _end_ area by adding the file [`layouts/partials/topbar/area/end.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/area/end.html) in your installation (not in the theme itself) to remove all but the _more_ button.
+
+The below example sets an explicit value for the `onempty` parameter, overriding the specific default value for this button (these defaults vary depending on the button). The parameter causes the _more_ button to always be displayed instead of hiding once its content is empty.
+
+````go
+{{ partial "topbar/button/more.html" (dict
+  "page" .
+  "onempty" "disable"
+)}}
+````
+
+## Defining Own Buttons
+
+### Button Types
+
+The theme distinguishes between two types of buttons:
+
+- [**button**](#button): a clickable button that either browses to another site, triggers a user-defined script or opens an overlay containing user-defined content
+- [**area-button**](#area-button): the template for the {{% button style="transparent" icon="ellipsis-v" %}}{{% /button %}} _more_ button, to define your own area overlay buttons
+
+### Button Parameter
+
+#### Screen Widths and Actions
+
+Depending on the screen width, you can configure how the button should behave. Screen width is divided into three classes:
+
+- **s**: (controlled by the `onwidths` parameter) mobile layout where the menu sidebar is hidden
+- **m**: (controlled by the `onwidthm` parameter) desktop layout with visible sidebar while the content area width still resizes
+- **l**: (controlled by the `onwidthl` parameter) desktop layout with visible sidebar once the content area reached its maximum width
+
+For each width class, you can configure one of the following actions:
+
+- `show`: the button is displayed in its given area
+- `hide`: the button is removed
+- `area-XXX`: the button is moved from its given area into the area `XXX`; for example, this is used to move buttons to the _more_ area overlay in the mobile layout
+
+#### Hiding and Disabling Stuff
+
+While hiding a button depending on the screen size can be configured with the above-described _hide_ action, you may want to hide the button on certain other conditions as well.
+
+For example, the _print_ button in its default configuration should only be displayed if print support was configured. This is done in your button template by checking the conditions first before displaying the button (see [`layouts/partials/topbar/button/print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/print.html)).
+
+Another preferred condition for hiding a button is if the displayed overlay is empty. This is the case for the _toc_ (see [`layouts/partials/topbar/button/toc.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/toc.html)) as well as the _more_ button (see [`layouts/partials/topbar/button/more.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/more.html)) and controlled by the parameter `onempty`.
+
+This parameter can have one of the following values:
+
+- `disable`: the button is displayed in a disabled state if the overlay is empty
+- `hide`: the button is removed if the overlay is empty
+
+If you want to disable a button containing _no overlay_, this can be achieved by an empty `href` parameter. An example can be seen in the _prev_ button (see `layouts/partials/topbar/button/prev.html`) where the URL for the previous site may be empty.
+
+## Reference
+
+### Button
+
+Contains the basic button functionality and is used as a base implementation for all other buttons ([`layouts/partials/topbar/func/button.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/func/button.html)).
+
+Call this from your own button templates if you want to implement a button without an overlay like the _print_ button ([`layouts/partials/topbar/button/print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/print.html)) or with an overlay containing arbitrary content like the _toc_ button ([`layouts/partials/topbar/button/toc.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/toc.html)).
+
+For displaying an area in the button's overlay, see [Area-Button](#area-button).
+
+#### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| **page**              | _<empty>_ | Mandatory reference to the page. |
+| **class**             | _<empty>_ | Mandatory unique class name for this button. Displaying two buttons with the same value for **class** is undefined. |
+| **href**              | _&lt;empty&gt;_ | Either the destination URL for the button or JavaScript code to be executed on click.<br><br>- If starting with `javascript:` all following text will be executed in your browser<br>- Every other string will be interpreted as URL<br>- If empty, the button will be displayed in a disabled state regardless of its **content** |
+| **icon**              | _&lt;empty&gt;_ | [Font Awesome icon name](shortcodes/icon#finding-an-icon). |
+| **onempty**           | `disable`       | Defines what to do with the button if the content parameter was set but ends up empty:<br><br>- `disable`: The button is displayed in a disabled state.<br>- `hide`: The button is removed. |
+| **onwidths**          | `show`          | The action that should be executed if the site is displayed in the given width:<br><br>- `show`: The button is displayed in its given area<br>- `hide`: The button is removed.<br>- `area-XXX`: The button is moved from its given area into the area `XXX`. |
+| **onwidthm**          | `show`          | See above. |
+| **onwidthl**          | `show`          | See above. |
+| **hint**              | _&lt;empty&gt;_ | Arbitrary text displayed in the tooltip. |
+| **title**             | _&lt;empty&gt;_ | Arbitrary text for the button. |
+| **content**           | _&lt;empty&gt;_ | Arbitrary HTML to put into the content overlay. This parameter may be empty. In this case, no overlay will be generated. |
+
+### Area-Button
+
+Contains the basic functionality to display area overlay buttons ([`layouts/partials/topbar/func/area-button.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/func/area-button.html)).
+
+Call this from your own button templates if you want to implement a button with an area overlay like the _more_ button ([`layouts/partials/topbar/button/more.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/more.html)).
+
+#### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| **page**              | _&lt;empty&gt;_ | Mandatory reference to the page. |
+| **area**              | _&lt;empty&gt;_ | Mandatory unique area name for this area. Displaying two areas with the same value for **area** is undefined. |
+| **icon**              | _&lt;empty&gt;_ | [Font Awesome icon name](shortcodes/icon#finding-an-icon). |
+| **onempty**           | `disable`       | Defines what to do with the button if the content overlay is empty:<br><br>- `disable`: The button is displayed in a disabled state.<br>- `hide`: The button is removed. |
+| **onwidths**          | `show`          | The action that should be executed if the site is displayed in the given width:<br><br>- `show`: The button is displayed in its given area<br>- `hide`: The button is removed.<br>- `area-XXX`: The button is moved from its given area into the area `XXX`. |
+| **onwidthm**          | `show`          | See above. |
+| **onwidthl**          | `show`          | See above. |
+| **hint**              | _&lt;empty&gt;_ | Arbitrary text displayed in the tooltip. |
+| **title**             | _&lt;empty&gt;_ | Arbitrary text for the button. |
+
+### Predefined Buttons
+
+The predefined buttons by the theme (all other buttons besides the _more_ and _toc_ button in [`layouts/partials/topbar/button`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button)).
+
+Call these from your own redefined area templates if you want to use default button behavior.
+
+The _&lt;varying&gt;_ parameter values are different for each button and configured for standard behavior as seen on this page.
+
+#### Parameter
+
+| Name                  | Default           | Notes       |
+|-----------------------|-------------------|-------------|
+| **page**              | _&lt;empty&gt;_   | Mandatory reference to the page. |
+| **onwidths**          | _&lt;varying&gt;_ | The action that should be executed if the site is displayed in the given width:<br><br>- `show`: The button is displayed in its given area<br>- `hide`: The button is removed.<br>- `area-XXX`: The button is moved from its given area into the area `XXX`. |
+| **onwidthm**          | _&lt;varying&gt;_ | See above. |
+| **onwidthl**          | _&lt;varying&gt;_ | See above. |
+
+### Predefined Overlay-Buttons
+
+The predefined buttons by the theme that open an overlay (the _more_ and _toc_ button in [`layouts/partials/topbar/button`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button)).
+
+Call these from your own redefined area templates if you want to use default button behavior utilizing overlay functionality.
+
+The _&lt;varying&gt;_ parameter values are different for each button and configured for standard behavior as seen on this page.
+
+#### Parameter
+
+| Name                  | Default           | Notes       |
+|-----------------------|-------------------|-------------|
+| **page**              | _&lt;empty&gt;_   | Mandatory reference to the page. |
+| **onempty**           | `disable`         | Defines what to do with the button if the content overlay is empty:<br><br>- `disable`: The button is displayed in a disabled state.<br>- `hide`: The button is removed. |
+| **onwidths**          | _&lt;varying&gt;_ | The action that should be executed if the site is displayed in the given width:<br><br>- `show`: The button is displayed in its given area<br>- `hide`: The button is removed.<br>- `area-XXX`: The button is moved from its given area into the area `XXX`. |
+| **onwidthm**          | _&lt;varying&gt;_ | See above. |
+| **onwidthl**          | _&lt;varying&gt;_ | See above. |

docs/content/configuration/customization/topbar/_index.pir.md

@@ -0,0 +1,9 @@
++++
+categories = ["explanation", "reference"]
+description = "How to extend the topbar"
+options = ["editURL"]
+outputs = ["html", "rss", "print", "markdown", "source"]
+title = "Topbarrr"
+weight = 4
++++
+{{< piratify >}}

docs/content/configuration/reference/_index.en.md

@@ -0,0 +1,38 @@
++++
+categories = ["reference"]
+description = "All configuration options for the Relearn theme"
+title = "Options Reference"
+weight = 6
++++
+
+This page explains how to configure the Relearn theme in your `hugo.toml` file.
+
+In addition to [Hugo's standard options](https://gohugo.io/getting-started/configuration/#all-configuration-settings), the Relearn theme offers extra settings listed here.
+
+Throughout the documentation, theme-specific options are marked with a {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} badge.
+
+Add theme options to the `params` section of your `hugo.toml`. For example:
+
+{{< multiconfig file=hugo >}}
+[params]
+  math = true
+{{< /multiconfig >}}
+
+## Index
+
+{{% taxonomy "options" "h3" %}}
+
+## All Configuration Options
+
+Here's a list of all available options with example values. Default values are described in the [annotated example](#annotated-configuration-options) below in each option's documentation.
+
+{{< multiconfig file=hugo section=params >}}
+{{% include "config/_default/params.toml" %}}
+{{< /multiconfig >}}
+
+## Annotated Configuration Options
+
+````toml {title="hugo.toml"}
+[params]
+{{% include "config/_default/params.toml" %}}
+````

docs/content/configuration/reference/_index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["reference"]
+description = "All configuration options for the Relearn theme"
+title = "Options Reference"
+weight = 6
++++
+{{< piratify >}}

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

@@ -0,0 +1,9 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Configure all things sidebar"
+title = "Sidebar"
+weight = 3
++++
+
+{{% children containerstyle="div" style="h2" description=true %}}

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

@@ -0,0 +1,8 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Configure all things sidebar"
+title = "Sidebar"
+weight = 3
++++
+{{< piratify >}}

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

@@ -0,0 +1,62 @@
++++
+categories = ["howto"]
+description = "Configure the header and footer"
+options = ["disableLandingPageButton", "landingPageName", "linkTitle", "showVisitedLinks"]
+title = "Header & Footer"
+weight = 2
++++
+
+## Title
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} With the [default partials](configuration/branding/logo#change-the-logo) for the logo, The site title will also be used for the text at the top of the sidebar. If you want to show a different text in the sidebar, you can overwrite `linkTitle`.
+
+{{< multiconfig file=hugo >}}
+[params]
+  linkTitle = 'Relearn'
+{{< /multiconfig >}}
+
+## Home Button Configuration
+
+By default, the theme displays a home button between search form and navigation menu. The Home button serves as an alternative to clicking the logo.
+
+![Default Home Button](home_button_defaults.png?width=18.75rem)
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} To hide the Home button on the left menu, set `disableLandingPageButton=true`.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableLandingPageButton = true
+{{< /multiconfig >}}
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} To change its icon or text, configure the `landingPageName` for your defined languages.
+
+{{< multiconfig file=hugo >}}
+[languages]
+  [languages.en]
+    [languages.en.params]
+      landingPageName = '<i class="fa-fw fas fa-home"></i> Home'
+
+  [languages.pir]
+    [languages.pir.params]
+      landingPageName = '<i class="fa-fw fas fa-home"></i> Arrr! Homme'
+{{< /multiconfig >}}
+
+If this option isn't set for a specific language, it will use these default values
+
+{{< multiconfig file=hugo >}}
+[params]
+  landingPageName = '<i class="fa-fw fas fa-home"></i> Home'
+{{< /multiconfig >}}
+
+## History
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Turn on `showVisitedLinks=true` to see checkmarks next to visited pages in the main menu. This also adds a `Clear History` option at the bottom of the menu to remove all checkmarks. Note that checkmarks will disappear if you rebuild your site, as the page IDs may change.
+
+{{< multiconfig file=hugo >}}
+[params]
+  showVisitedLinks = true
+{{< /multiconfig >}}
+
+## Footer
+
+To change the menu footer, edit the `layouts/partials/menu-footer.html` file. Check out the [Partials section](configuration/customization/partials) for more ways to customize your site.

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

@@ -0,0 +1,8 @@
++++
+categories = ["howto"]
+description = "Configure the header and footer"
+options = ["disableLandingPageButton", "landingPageName", "linkTitle", "showVisitedLinks"]
+title = "Header & Footer"
+weight = 2
++++
+{{< piratify >}}

docs/content/configuration/sidebar/menus/_index.en.md

@@ -0,0 +1,337 @@
++++
+categories = ["howto"]
+description = "Configure all things menus"
+frontmatter = ["alwaysopen", "collapsibleMenu", "linkTitle", "menuPageRef", "menuPost", "menuPre", "menuUrl", "ordersectionsby", "sidebarmenus"]
+options = ["alwaysopen", "collapsibleMenu", "disableShortcutsTitle", "ordersectionsby",  "sidebarmenus"]
+title = "Menus"
+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/).
+
+---
+
+- {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Configuration options in your `hugo.toml` apply to all menus.
+
+- {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} In case of page structure menus, individual configuration is done via a page's front matter.
+
+- {{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}}. In case of Hugo menus, individual configuration is done via a menu entry's configuration.
+
+---
+
+## Expand State of Submenus
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can change how submenus appear with `alwaysopen`.
+
+{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} For Hugo menus, you have to set `params.alwaysopen` instead.
+
+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 expand state based on the following rules:
+
+- all parent entries of the active page including their [visible](authoring/meta#hidden) siblings are shown regardless of any settings
+- immediate child entries of the active entry 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](authoring/meta#hidden) entries show their immediate child entries if `alwaysopen=true`; this proceeds recursively
+- all remaining entries are not shown
+
+{{< multiconfig >}}
+alwaysopen = false
+{{< /multiconfig >}}
+
+## Expander for Submenus
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Set `collapsibleMenu=true` to show submenus as collapsible trees with a clickable expander.
+
+{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} For Hugo menus, you have to set `params.collapsibleMenu=true` instead.
+
+{{< multiconfig >}}
+collapsibleMenu = true
+{{< /multiconfig >}}
+
+> [!WARNING]
+> Using this option may cause degraded build performance by slowing down your build process.
+>
+> This is usually the case for menus with many entries and happens for page menus as well as for Hugo menus.
+>
+> We've seen builds taking 2 minutes with 1000+ pages, and over 30 minutes with 5000+ pages when using a page menu.
+>
+> This happens because each new page affects all other pages, leading to exponentially longer build times.
+
+## Ordering Menu Entries
+
+### By Weight
+
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} {{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} Hugo provides a [simple way](https://gohugo.io/getting-started/glossary/#weight) to handle order of your entries by setting the `weight` front matter to a number.
+
+Hugo menus can only be sorted using the weight method.
+
+{{< multiconfig>}}
+weight = 5
+{{< /multiconfig >}}
+
+### By 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 %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Use `ordersectionsby` to sort by other aspects. See the [children shortcode](shortcodes/children#parameter) for a complete list.
+
+{{< multiconfig >}}
+ordersectionsby = 'linktitle'
+{{< /multiconfig >}}
+
+## Title for Menu Entries
+
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} A page's `linkTitle` or `title` front matter will be used for naming a menu entry of a page menu, in that order if both are defined. Using `linkTitle` helps to shorten the text for menu entries if the page’s title is too descriptive.
+
+{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} A menu entry's `title` or `name` will be used for naming a menu entry of a Hugo menu, in that order if both are defined.
+
+For example for a page named `install/linux.md`
+
+{{< multiconfig fm=true >}}
+title = 'Install on Linux'
+linkTitle = 'Linux'
+{{< /multiconfig >}}
+
+## Icons for Menu Entries
+
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} For page menus, 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.
+
+{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} For Hugo menus, add a `pre` to insert any HTML code before the menu label. You can also set `post` to insert HTML code after the menu label.
+
+If `pageRef` is set for the menu entry and no `pre` or `post` was configured, `menuPre` and `menuPost` of the referenced page will be taken.
+
+The example below uses the GitHub icon for an entry of a page menu.
+
+{{< multiconfig fm=true >}}
+title = 'GitHub Repo'
+menuPre = '<i class="fab fa-github"></i> '
+{{< /multiconfig >}}
+
+## Disable Menu Entries
+
+You may want to structure your entries in a hierarchical way but don't want to generate clickable parent entries? The theme got you covered.
+
+### For Page Menus
+
+To stay with the [initial example](authoring/structure): Suppose you want `first-chapter/first-page` 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 be expandable.
+
+For this, open `content/first-chapter/first-page/_index.md` and add the following front matter
+
+{{< multiconfig fm=true >}}
+[_build]
+  render = 'never'
+{{< /multiconfig >}}
+
+### For Hugo Menus
+
+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'
+  weight = 1
+
+[[menu.addendum]]
+  parent = 'Parent 1'
+  name = 'Child 1'
+  url = 'https://example.com/1'
+
+[[menu.addendum]]
+  name = 'Parent 2'
+  weight = 2
+
+[[menu.addendum]]
+  parent = 'Parent 2'
+  name = 'Child 2'
+  url = 'https://example.com/2'
+{{< /multiconfig >}}
+
+## Title for Menus
+
+Each menu may have an optional title above its tree. This must be activated for each [menu by setting `disableMenuTitle=false` for each sidebar menu configuration](#parameter).
+
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} For page menus, set the `menuTitle` front matter for the root page of the menu. For example in the home page for the default sidebar menu. If no `menuTitle` was set, the title will be taken from your translation files by the key `<identifier>-menuTitle`, where `<identifier>` is the identifier of your sidebar menu configuration.
+
+{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} For Hugo menus, the title will be taken from your translation files by the key `<identifier>-menuTitle`, where `<identifier>` is the identifier of your sidebar menu configuration.
+
+If you don't want to fiddle around with your translation files, you also have the possibility to let the title be taken from the menu definition. For that, define a nested menu that only has one top-level entry without `url` or `pageRef`.
+
+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'
+
+[[menu.addendum]]
+  parent = 'Parent'
+  name = 'A Menu Entry Title for Child 1'
+  url = 'https://example.com/1'
+  weight = 1
+
+[[menu.addendum]]
+  parent = 'Parent'
+  name = 'A Menu Entry Title for Child 2'
+  url = 'https://example.com/2'
+  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.
+
+You can define as many menus, as you like. If you don't overwrite this option, the theme defaults to
+
+{{< multiconfig >}}
+sidebarmenus = [
+  { type = 'page', identifier = 'home', main = true, disableTitle = true, pageRef = '' },
+  { type = 'menu', identifier = 'shortcuts', main = false, disableTitle = false },
+]
+{{< /multiconfig >}}
+
+### Parameter
+
+| Name                  | Default         | Notes       |
+|-----------------------|-----------------|-------------|
+| type                  | _&lt;empty&gt;_ | The type of menu.<br><br>- `page` for a page menu<br>- `menu` for a Hugo menu |
+| identifier            | _&lt;empty&gt;_ | A unique identifier for this entry<br><br>- for `type=page` an arbitrary name<br>- for `page=menu` the identifier of the menu definition in your `hugo.toml` |
+| main                  | see notes       | Whether to add additional spacing and larger text to the menu<br><br>- for `type=page` defaults to `true`<br>- for `page=menu` defaults to `false` |
+| disableTitle          | see notes       | Whether to print a title above the menu<br><br>- for `type=page` defaults to `true`<br>- for `page=menu` defaults to `false` |
+| pageRef               | _&lt;empty&gt;_ | Only for `type=page`, the page path to start the menu tree. If not set, defaults to the home page. |
+
+## Redefining Sidebar Menus for Certain Pages
+
+Suppose you are building a site that contains a topmost `blog` and `documentation` section.
+
+When the user is on one of the blog pages he should only see a page menu containing all blog pages, while on a documentation page he should only see a page menu containing all doc pages.
+
+For both sections, the default `shortcuts` Hugo menu should be displayed as if [defaults menus](#defining-sidebar-menus) were used.
+
+Directory structure:
+
+````plaintext
+content
+├── blog
+│   ├── post-1.md
+│   ├── post-2.md
+│   ├── post-3.md
+│   └── _index.md
+├── docs
+│   ├── topic-1.md
+│   ├── topic-2.md
+│   ├── topic-3.md
+│   └── _index.md
+└── _index.md
+````
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Using [Hugo's cascade feature](https://gohugo.io/content-management/front-matter/#cascade), we can redefine the menus once in `blog/_index.md` and `docs/_index.md` setting `sidebarmenus` so they will be used in all children pages.
+
+Setting the `sidebarmenus` Front Matter will overwrite all default menus. If you want to display the `shortcuts` Hugo menu as well like in this example, you have to declare it with the Front Matter as given in the [default options](#defining-sidebar-menus).
+
+{{< multiconfig fm=true file="blog/_index.md">}}
+title = 'Blog'
+[[cascade]]
+  [cascade.params]
+    sidebarmenus = [
+      { type = 'page', identifier = 'blog', pageRef = '/blog' },
+      { type = 'menu', identifier = 'shortcuts' },
+    ]
+{{< /multiconfig >}}
+
+{{< multiconfig fm=true file="docs/_index.md">}}
+title = 'Documentation'
+[[cascade]]
+  [cascade.params]
+    sidebarmenus = [
+      { type = 'page', identifier = 'docs', pageRef = '/docs' },
+      { type = 'menu', identifier = 'shortcuts' },
+    ]
+{{< /multiconfig >}}
+
+## Displaying Arbitrary Links in a Page Menu
+
+You may have the need to add arbitrary links at some point in your menu that are initially not backed by a page. These are called crosslinks.
+
+Assume the following structure
+
+````plaintext
+content
+├── reference
+│   ├── ref-a.md
+│   ├── ref-b.md
+│   ├── ref-c.md
+│   └── _index.md
+├── topic-blue.md
+├── topic-red.md
+├── topic-yellow.md
+└── _index.md
+````
+
+You now want to include `ref-b` as separate `topic-green` entry after `topic-blue` in your menu.
+
+For that create a new page with the following front matter
+
+{{< multiconfig fm=true file="content/topic-green.md" >}}
+title = 'Topic Green'
+menuPageRef = '/reference/ref-b'
+{{< /multiconfig >}}
+
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} If you want to link to an external page instead, you can use `menuUrl` instead of `menuPageRef`.
+
+Pages defining a crosslink are never part of the arrow navigation and are skipped instead.
+
+So with the above example and alphabetical sorting of the menu entries, pressing {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} on `topic-blue` will skip the newly added `topic-green` and instead will load `topic-red`.
+
+Having sub pages below a page that has `menuUrl` or `menuPageRef` set in their front matter is undefined.
+
+## Displaying Pages Exclusively in a Hugo Menu
+
+Sometimes you want to hide pages from the page menu but instead want to show them in a Hugo menu. For that you have two choices
+
+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 >}}

docs/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 >}}

docs/content/configuration/sidebar/search/_index.en.md

@@ -0,0 +1,72 @@
++++
+categories = ["howto"]
+description = "Configure search and the search form"
+options = ["additionalContentLanguage", "disableSearch", "disableSearchIndex", "disableSearchPage", "searchIndexURL", "searchPageURL"]
+title = "Search"
+weight = 3
++++
+
+## Configure Search
+
+The theme offers three levels of search through the menu's search form:
+
+1. In-page search: Highlights search terms on the current page
+2. Search popup: Opens a popup with results from other pages
+3. Dedicated search page: Accessible by clicking the magnifier glass or pressing <kbd>ENTER</kbd>
+
+Each level requires the previous one to be enabled. If no search is configured, the search form won't appear.
+
+{{%badge style="cyan" icon="gears" title=" "%}}Option{{%/badge%}} All levels are enabled by default. Disable them in `hugo.toml`:
+
+- In-page search: `disableSearch=true`
+- Search popup: `disableSearchIndex=true`
+- Dedicated search page: `disableSearchPage=true`
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableSearch = true
+  disableSearchIndex = true
+  disableSearchPage = true
+{{< /multiconfig >}}
+
+{{%badge style="cyan" icon="gears" title=" "%}}Option{{%/badge%}} Default URLs can be changed with the following parameter
+
+- Search popup: `searchindex.js` set by `searchIndexURL`
+- Dedicated search page: `search/index.html` set by `searchPageURL`
+
+{{< multiconfig file=hugo >}}
+[params]
+  searchIndexURL = 'omnisearchindex.js'
+  searchPageURL = 'omnisearch'
+{{< /multiconfig >}}
+
+{{% notice note %}}
+You only need to change these if you have other own content created for those URLs. This can happen with `uglyURLs=true` in `hugo.toml` and having a content file at `content/search.md`.
+
+Check for duplicate URLs by running `hugo --printPathWarnings`.
+{{% /notice %}}
+
+## Supported Languages
+
+The [Lunr](https://lunrjs.com) search library doesn't support all languages of the theme. Unsupported languages will show errors in the browser console. Currently unsupported are
+
+- Czech
+- Indonesian
+- Persian
+- Polish
+- Swahili
+
+## Mixed Language Support
+
+{{%badge style="cyan" icon="gears" title=" "%}}Option{{%/badge%}} In case your page's content contains text in multiple languages (for example, you are writing a Piratish documentation for your English API), you can set those languages in `additionalContentLanguage` to broaden the search.
+
+{{< multiconfig file=hugo >}}
+[params]
+  additionalContentLanguage = [ "en" ]
+{{< /multiconfig >}}
+
+You can add multiple languages to this array.
+
+{{% notice note %}}
+Use the base language code. For example, if your page is using `zh-CN`, add `zh` to this parameter.
+{{% /notice %}}

docs/content/configuration/sidebar/search/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["howto"]
+description = "Configure search and the search form"
+options = ["additionalContentLanguage", "disableSearch", "disableSearchIndex", "disableSearchPage", "searchIndexURL", "searchPageURL"]
+title = "Search"
+weight = 3
++++
+{{< piratify >}}

docs/content/configuration/sidebar/width/_index.en.md

@@ -0,0 +1,34 @@
++++
+categories = ["howto"]
+description = "Changing the width of the sidebar"
+title = "Width"
+weight = 1
++++
+
+The theme adjusts the menu width based on browser size.
+
+If you want to change the chosen default width, you can add CSS variables to `layouts/partials/custom-header.html`.
+
+## Changing Menu Width
+
+The menu width changes for different screen sizes:
+
+| Screen Size | Screen Width  | Menu Width |
+| ----------- | ------------- | ---------- |
+| Small       | < 48rem       | 14.375rem  |
+| Medium      | 48rem - 60rem | 14.375rem  |
+| Large       | >= 60rem      | 18.75rem   |
+
+You can change the menu width but not the screen width breakpoints.
+
+To adjust the menu width, use these CSS variables. Note that `--MENU-WIDTH-S` is for the mobile menu flyout on small screens.
+
+````html {title="layouts/partials/custom-header.html"}
+<style>
+:root {
+    --MENU-WIDTH-S: 14.375rem;
+    --MENU-WIDTH-M: 14.375rem;
+    --MENU-WIDTH-L: 18.75rem;
+}
+</style>
+````

docs/content/configuration/sidebar/width/_index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["howto"]
+description = "Changing the width of the sidebar"
+title = "Width"
+weight = 1
++++
+{{< piratify >}}

docs/content/configuration/sitemanagement/_index.en.md

@@ -0,0 +1,9 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Get yourself familiar with the general structure of your website"
+title = "Site Management"
+weight = 1
++++
+
+{{% children containerstyle="div" style="h2" description=true %}}

docs/content/configuration/sitemanagement/_index.pir.md

@@ -0,0 +1,8 @@
++++
+alwaysopen = false
+categories = ["reference"]
+description = "Get yourself familiar with the general structure of your website"
+title = "Site Management"
+weight = 1
++++
+{{< piratify >}}

docs/content/configuration/sitemanagement/deployment/_index.en.md

@@ -0,0 +1,61 @@
++++
+categories = ["howto"]
+description = "Options for specific deployment needs"
+title = "Deployment Scenarios"
+weight = 4
++++
+
+## Offline Usage
+
+The theme is usable offline. No internet connection is required to load your page. This is achieved by storing all dependencies within the theme.
+
+No calls to 3rd party servers, no calling home, no tracking. Privacy friendly.
+
+## Server Deployment
+
+If your server deployment has no special requirements, you can skip this section and use the [standard Hugo options](https://gohugo.io/content-management/urls/).
+
+For special requirements, the theme is capable of different scenarios, requiring the following mandatory settings in your `hugo.toml`. All settings not mentioned in the examples below can be set to your liking.
+
+### Public Web Server from Root
+
+{{< multiconfig file=hugo >}}
+baseURL = 'https://example.com/'
+{{< /multiconfig >}}
+
+### Public Web Server from Subdirectory
+
+{{< multiconfig file=hugo >}}
+baseURL = 'https://example.com/mysite/'
+relativeURLs = false
+{{< /multiconfig >}}
+
+If you are still using Hugo's `relref` shortcode (which you shouldn't), you will need [further configuration](configuration/content/linking#patching-the-relref-shortcode).
+
+> [!WARNING]
+> Don't use a `baseURL` with a subdirectory and `relativeURLs=true` together. [Hugo doesn't apply the `baseURL` correctly](https://github.com/gohugoio/hugo/issues/12130) in this case. If you need both, generate your site twice with different settings into separate directories.
+
+### Private Web Server (LAN)
+
+The same settings as with any of the public web server scenarios or
+
+{{< multiconfig file=hugo >}}
+baseURL = '/'
+relativeURLs = true
+{{< /multiconfig >}}
+
+### File System
+
+Your generated site can be used headless without a HTTP server.
+
+This can be achieved by using the `file://` protocol in your browser's address bar or by double click on a generated `*.html` file in your file navigation tool.
+
+Use the following settings
+
+{{< multiconfig file=hugo >}}
+baseURL = '/'
+relativeURLs = true
+{{< /multiconfig >}}
+
+> [!note]
+> Pages like `sitemap.xml` and `rss.xml`, and social media links will always use absolute URLs. They won't work with `relativeURLs=true`.

docs/content/configuration/sitemanagement/deployment/_index.pir.md

@@ -0,0 +1,7 @@
++++
+categories = ["howto"]
+description = "Options for specific deployment needs"
+title = "Deployment Scenarios"
+weight = 4
++++
+{{< piratify >}}

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

@@ -0,0 +1,43 @@
++++
+categories = ["howto"]
+description = "What site-wide meta information can be set"
+frontmatter = ["description"]
+options = ["author.email", "author.name"]
+title = "Meta Information"
+weight = 3
++++
+
+## Site Author Information
+
+{{% 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]
+  [params.author]
+    name = 'Santa Claus'
+    email = 'santa@example.com'
+{{< /multiconfig >}}
+
+## Site Title
+
+The `title` will be used in meta information of your HTML.
+
+{{< multiconfig file=hugo >}}
+title = 'Hugo Relearn Theme'
+{{< /multiconfig >}}
+
+## Site Description
+
+{{% 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
+
+When your page is shared on social media, you can set a site-wide image to display with the link
+
+{{< multiconfig file=hugo >}}
+images = [ 'images/hero.png' ]
+{{< /multiconfig >}}
+
+## More Social Media Options
+
+The theme adheres to Hugo's official documentation for [Open Graph](https://gohugo.io/templates/embedded/#configure-open-graph) and [Twitter Cards](https://gohugo.io/templates/embedded/#configure-x-twitter-cards) configuration.

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

@@ -0,0 +1,9 @@
++++
+categories = ["howto"]
+description = "What site-wide meta information can be set"
+frontmatter = ["description"]
+options = ["author.email", "author.name"]
+title = "Meta Information"
+weight = 3
++++
+{{< piratify >}}

docs/content/configuration/sitemanagement/multilingual/_index.en.md

@@ -0,0 +1,102 @@
++++
+categories = ["howto"]
+description = "How to set up a multilingual site"
+options = ["disableLanguageSwitchingButton"]
+title = "Multilingual"
+weight = 2
++++
+
+The Relearn theme works with [Hugo's multilingual mode](https://gohugo.io/content-management/multilingual/).
+
+It supports many languages, including right-to-left languages.
+
+{{% expand "Supported languages" %}}
+- Arabic
+- Simplified Chinese
+- Traditional Chinese
+- Czech
+- Dutch
+- English
+- Finnish
+- French
+- German
+- Hindi
+- Hungarian
+- Indonesian
+- Italian
+- Japanese
+- Korean
+- Persian
+- Polish
+- Portuguese
+- Romanian
+- Russian
+- Spanish
+- Swahili
+- Turkish
+- Vietnamese
+{{% /expand %}}
+
+## Translation by File Name
+
+Here's how to make your site multilingual using [translations by file name](https://gohugo.io/content-management/multilingual/#translation-by-file-name):
+
+1. Set up languages in your `hugo.toml` file:
+
+    {{< multiconfig file=hugo >}}
+    defaultContentLanguage = 'en'
+
+    [languages]
+      [languages.en]
+        weight = 1
+        languageName = 'English'
+        languageCode = 'en'
+        title = 'My Website'
+
+      [languages.pir]
+        weight = 2
+        languageName = 'Pirrratish'
+        languageCode = 'art-x-pir'
+        languageDirection = 'rtl'
+        title = 'Arrr, my Website'
+    {{< /multiconfig >}}
+
+2. Duplicate your content files and add language codes to their file names:
+
+    ````plaintext
+    ├── content
+    │   ├── first-chapter
+    │   │   ├── first-page
+    |   |   |   ├── _index.en.md
+    |   |   |   └── _index.pir.md
+    │   │   ├── second-page
+    |   |   |   ├── index.en.md
+    |   |   |   └── index.pir.md
+    │   │   ├── third-page.en.md
+    │   │   └── third-page.pir.md
+    │   ├── _index.en.md
+    │   └── _index.pir.md
+    ├── themes
+    │   └── hugo-theme-relearn
+    │       └── ...
+    └── hugo.toml
+    ````
+
+## Translation by Content Directory
+
+The theme also support [translations by content directory](https://gohugo.io/content-management/multilingual/#translation-by-content-directory) which can be configured in a similar way. This is not used in further examples of this documentation.
+
+## Search Settings
+
+Check the [search configuration](configuration/sidebar/search#mixed-language-support) for multilingual options.
+
+## Turn Off Language Switching
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default the theme shows a language switcher in the lower part of the menu.
+
+To disable the language switcher set `disableLanguageSwitchingButton=true`
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableLanguageSwitchingButton = true
+{{< /multiconfig >}}

docs/content/configuration/sitemanagement/multilingual/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["howto"]
+description = "How to set up a multilingual site"
+options = ["disableLanguageSwitchingButton"]
+title = "Multilingual"
+weight = 2
++++
+{{< piratify >}}

docs/content/configuration/sitemanagement/outputformats/_index.en.md

@@ -0,0 +1,86 @@
++++
+categories = ["howto"]
+description = "What formats can a page be displayed in"
+outputs = ["html", "rss", "print", "markdown", "source"]
+title = "Available Output Formats"
+weight = 5
++++
+
+The Relearn theme by default comes with templates for HTML and RSS for each page.
+
+In addition you can configure the below formats.
+
+If this is not enough, learn how to [create your own output formats](configuration/customization/outputformats).
+
+## Print Support
+
+Enable print support to print entire chapters or the whole site. Add the `print` output format to your home, section, and page in `hugo.toml`:
+
+{{< multiconfig file=hugo >}}
+[outputs]
+  home = ['html', 'rss', 'print']
+  section = ['html', 'rss', 'print']
+  page = ['html', 'rss', 'print']
+{{< /multiconfig >}}
+
+By default this adds a printer icon in the topbar but [can be deactived](authoring/frontmatter/topbar/#print-button). Clicking it switches to print preview, showing the page and its [visible subpages](configuration/content/hidden) in a printer-friendly format. Use your browser's print function to print or save as PDF.
+
+The URL won't be [configured ugly](https://gohugo.io/templates/output-formats/#configure-output-formats) for [Hugo's URL handling](https://gohugo.io/content-management/urls/#ugly-urls), even with `uglyURLs=true` in `hugo.toml`. This is because each mime type can only have one suffix.
+
+If you don't like the URLs, you can reconfigure `outputFormats.print` in your `hugo.toml` to something other than the default of:
+
+{{< multiconfig file=hugo >}}
+[outputFormats]
+  [outputFormats.print]
+    name= 'print'
+    baseName = 'index.print'
+    isHTML = true
+    mediaType = 'text/html'
+    permalinkable = false
+    noUgly = true
+{{< /multiconfig >}}
+
+## Markdown Support
+
+Enable support to show the Markdown source of a page. Add the `markdown` output format to your home, section, and page in `hugo.toml`:
+
+{{< multiconfig file=hugo >}}
+[outputs]
+  home = ['html', 'rss', 'markdown']
+  section = ['html', 'rss', 'markdown']
+  page = ['html', 'rss', 'markdown']
+{{< /multiconfig >}}
+
+By default this adds a Markdown icon in the topbar but [can be deactived](authoring/frontmatter/topbar/#markdown-button). Clicking it switches to the Markdown source including the title of the page.
+
+The `markdown` output format configuration is [provided by Hugo](https://gohugo.io/templates/output-formats/#output-format-definitions).
+
+## Source Support
+
+Enable support to show the source code of a page if it was generated from a file. Add the `source` output format to your home, section, and page in `hugo.toml`:
+
+{{< multiconfig file=hugo >}}
+[outputs]
+  home = ['html', 'rss', 'source']
+  section = ['html', 'rss', 'source']
+  page = ['html', 'rss', 'source']
+{{< /multiconfig >}}
+
+By default this adds a Source icon in the topbar but [can be deactived](authoring/frontmatter/topbar/#source-button). Clicking it switches to the source code of the page.
+
+The Source output format differs from the Markdown format, as it prints the source code _as is_ including the front matter.
+
+The URL won't be [configured ugly](https://gohugo.io/templates/output-formats/#configure-output-formats) for [Hugo's URL handling](https://gohugo.io/content-management/urls/#ugly-urls), even with `uglyURLs=true` in `hugo.toml`. This is because each mime type can only have one suffix.
+
+If you don't like the URLs, you can reconfigure `outputFormats.source` in your `hugo.toml` to something other than the default of:
+
+{{< multiconfig file=hugo >}}
+[outputFormats]
+  [outputFormats.source]
+    name= 'source'
+    baseName = 'index.source'
+    isHTML = false
+    mediaType = 'text/markdown'
+    permalinkable = false
+    noUgly = true
+{{< /multiconfig >}}

docs/content/configuration/sitemanagement/outputformats/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["howto"]
+description = "What formats can a page be displayed in"
+outputs = ["html", "rss", "print", "markdown", "source"]
+title = "Available Output Formats"
+weight = 5
++++
+{{< piratify >}}

docs/content/configuration/sitemanagement/stableoutput/_index.en.md

@@ -0,0 +1,57 @@
++++
+categories = ["howto"]
+description = "How to make your generated HTML output stable"
+options = ["disableAssetsBusting", "disableGeneratorVersion", "disableRandomIds", "minify"]
+title = "Stable Output"
+weight = 6
++++
+
+## Disabling the Generator Meta
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} The theme adds a meta tag with its version number to each page.
+
+This isn't a security risk and helps us support you better.
+
+To turn this off, set `disableGeneratorVersion=true`.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableGeneratorVersion = true
+{{< /multiconfig >}}
+
+If you also want to turn off [Hugo's version meta tag](https://gohugo.io/getting-started/configuration/#disablehugogeneratorinject), use `disableHugoGeneratorInject=true`.
+
+## Disabling IDs for Referenced Assets
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} The theme creates a unique ID for each build and adds it to each referenced asset's URL to make browsers not keep outdated cached assets.
+
+This is good for production sites but can be problematic during development. It makes comparing outputs difficult as each build has new IDs.
+
+To disable this, set `disableAssetsBusting=true`.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableAssetsBusting = true
+{{< /multiconfig >}}
+
+## Disabling IDs for Interactive HTML Elements
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Features like expanders, callouts, and tabs use unique IDs to work. These IDs change with each build.
+
+This is necessary for the theme to work properly, but it can make comparing outputs between builds difficult.
+
+To turn this off, set `disableRandomIds=true`. Note, that this will result in a non-functional site!.
+
+{{< multiconfig file=hugo >}}
+[params]
+  disableRandomIds = true
+{{< /multiconfig >}}
+
+## Disabling Assets Minification
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} If `minify=true`, further theme assets will be minified during build. If no value is set, the theme will avoid minification if you have started with `hugo server` and otherwise will minify.
+
+{{< multiconfig file=hugo >}}
+[params]
+  minify = false
+{{< /multiconfig >}}

docs/content/configuration/sitemanagement/stableoutput/_index.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["howto"]
+description = "How to make your generated HTML output stable"
+options = ["disableAssetsBusting", "disableGeneratorVersion", "disableRandomIds", "minify"]
+title = "Stable Output"
+weight = 6
++++
+{{< piratify >}}

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

@@ -0,0 +1,38 @@
++++
+categories = ["explanation"]
+description = "Your site's directory structure"
+title = "Directory Structure"
+weight = 1
++++
+
+If you've followed the [Getting Started](introduction/quickstart) guide, your directory layout will look similar to this:
+
+````plaintext
+├── content
+│   ├── first-chapter
+│   │   ├── first-page
+|   |   |   └── _index.md
+│   │   ├── second-page
+|   |   |   └── index.md
+│   │   └── third-page.md
+│   └── _index.md
+├── themes
+│   └── hugo-theme-relearn
+│       └── ...
+└── hugo.toml
+````
+
+Hugo uses a [union file system](https://gohugo.io/getting-started/directory-structure/#union-file-system), which lets you combine multiple directories.
+
+By default, it puts your root directory on top of the Relearn theme directory. Files in your root directory will replace theme files in the same location.
+
+For example, if you create a file at `layouts/partials/heading.html`, it will override the theme's `themes/hugo-theme-relearn/layouts/partials/heading.html`.
+
+[See this list](configuration/customization/partials), to learn which files are allowed to be overridden by you.
+
+This makes it easy to customize the theme without changing files in the `themes` directory, making future theme updates simpler.
+
+> [!WARNING]
+> Don't edit files inside the `themes/hugo-theme-relearn` directory. That's not the recommended way to customize! Refer to the explanation above.
+>
+> Don't clone the theme repository and edit files there for your site.  That's not the recommended way to customize! Instead, follow the [Getting Started](introduction/quickstart) guide.

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

@@ -0,0 +1,7 @@
++++
+categories = ["explanation"]
+description = "Your site's directory structure"
+title = "Directory Structure"
+weight = 1
++++
+{{< piratify >}}

docs/content/development/_index.en.md

@@ -0,0 +1,12 @@
++++
+categories = ["reference"]
+menuPre = "<i class='fa-fw fas fa-code-pull-request'></i> "
+hidden = true
+title = "Development"
+type = "chapter"
+weight = 5
++++
+
+This chapter contains information only needed for development and maintaining the theme.
+
+{{%children containerstyle="div" style="h2" description="true" %}}

docs/content/development/_index.pir.md

@@ -0,0 +1,9 @@
++++
+categories = ["reference"]
+menuPre = "<i class='fa-fw fas fa-code-pull-request'></i> "
+hidden = true
+title = "Development"
+type = "chapter"
+weight = 5
++++
+{{< piratify >}}

docs/content/development/contributing/_index.en.md

@@ -0,0 +1,48 @@
++++
+categories = ["explanation"]
+description = "What to know if you want to contribute"
+title = "Contributing"
++++
+
+## Code Quality
+
+A new release can happen at any time from the `main` branch of the [GitHub project](https://github.com/McShelby/hugo-theme-relearn) without further acknowledgment. This makes it necessary that, every pushed set of changesets into the `main` branch **must** be self-contained and correct, resulting in a releasable version.
+
+Stay simple for the user by focusing on the mantra "convention over configuration".
+
+At installation the site should work reasonable without (m)any configuration.
+
+Stay close to the Hugo way.
+
+Don't use npm or any preprocessing, our contributors may not be front-end developers.
+
+Document new features in the docs. This also contains entries to the [What's new](introduction/releasenotes) page.
+
+Don't break existing features if you don't have to.
+
+Remove reported issue from the browser's console.
+
+Check for unnecessary whitespace and correct indention of your resulting HTML.
+
+## Conventional Commits
+
+Write commit messages in the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
+
+Following is an inpomplete list of some of the used conventional commit types. Be creative.
+
+| Common     | Feature    | Structure       | Shortcodes  |
+|------------|------------|-----------------|-------------|
+| build      | a11y       | favicon         | attachments |
+| browser    | archetypes | search          | badge       |
+| chore      | alias      | menu            | button      |
+| docs       | generator  | history         | children    |
+| shortcodes | i18n       | scrollbar       | expand      |
+| theme      | mobile     | nav             | icon        |
+|            | print      | toc             | include     |
+|            | rss        | clipboard       | math        |
+|            | variant    | syntaxhighlight | mermaid     |
+|            |            | boxes           | notice      |
+|            |            |                 | openapi     |
+|            |            |                 | piratify    |
+|            |            |                 | siteparam   |
+|            |            |                 | tabs        |