nishiki/hugo-theme-relearn
1
0
Fork 0
mirror of https://github.com/McShelby/hugo-theme-relearn.git synced 2025-05-28 12:34:04 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: move exampleSite to docs

Browse source
This commit is contained in:
Sören Weber 2025-01-29 23:30:53 +01:00
parent df03dac58f
commit db9ca5d295
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
827 changed files with 656 additions and 652 deletions

11
docs/content/configuration/_index.en.md Normal file
View file

@ -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 %}}

8
docs/content/configuration/_index.pir.md Normal file
View file

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

9
docs/content/configuration/branding/_index.en.md Normal file
View file

@ -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 %}}

8
docs/content/configuration/branding/_index.pir.md Normal file
View file

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

180
docs/content/configuration/branding/colors/_index.en.md Normal file
View file

@ -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`
});
````

8
docs/content/configuration/branding/colors/_index.pir.md Normal file
View file

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

29
docs/content/configuration/branding/generator/_index.en.md Normal file
View file

@ -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 %}}

8
docs/content/configuration/branding/generator/_index.pir.md Normal file
View file

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

41
docs/content/configuration/branding/logo/_index.en.md Normal file
View file

@ -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>
````

7
docs/content/configuration/branding/logo/_index.pir.md Normal file
View file

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

36
docs/content/configuration/branding/modules/_index.en.md Normal file
View file

@ -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)

7
docs/content/configuration/branding/modules/_index.pir.md Normal file
View file

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

9
docs/content/configuration/content/_index.en.md Normal file
View file

@ -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 %}}

8
docs/content/configuration/content/_index.pir.md Normal file
View file

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

29
docs/content/configuration/content/headings/index.en.md Normal file
View file

@ -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 >}}

8
docs/content/configuration/content/headings/index.pir.md Normal file
View file

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

44
docs/content/configuration/content/hidden/_index.en.md Normal file
View file

@ -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 >}}

8
docs/content/configuration/content/hidden/_index.pir.md Normal file
View file

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

35
docs/content/configuration/content/linking/index.en.md Normal file
View file

@ -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 >}}

8
docs/content/configuration/content/linking/index.pir.md Normal file
View file

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

33
docs/content/configuration/content/titles/index.en.md Normal file
View file

@ -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 >}}

8
docs/content/configuration/content/titles/index.pir.md Normal file
View file

@ -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 >}}

24
docs/content/configuration/content/width/_index.en.md Normal file
View file

@ -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>
````

7
docs/content/configuration/content/width/_index.pir.md Normal file
View file

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

9
docs/content/configuration/customization/_index.en.md Normal file
View file

@ -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 %}}

8
docs/content/configuration/customization/_index.pir.md Normal file
View file

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

148
docs/content/configuration/customization/designs/index.en.md Normal file
View file

@ -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>
````

7
docs/content/configuration/customization/designs/index.pir.md Normal file
View file

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

63
docs/content/configuration/customization/extending/_index.en.md Normal file
View file

@ -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.

8
docs/content/configuration/customization/extending/_index.pir.md Normal file
View file

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

82
docs/content/configuration/customization/imageeffects.en.md Normal file
View file

@ -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>
````

8
docs/content/configuration/customization/imageeffects.pir.md Normal file
View file

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

229
docs/content/configuration/customization/outputformats/_index.en.md Normal file
View file

@ -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>
````

7
docs/content/configuration/customization/outputformats/_index.pir.md Normal file
View file

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

46
docs/content/configuration/customization/partials/index.en.md Normal file
View file

@ -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.

7
docs/content/configuration/customization/partials/index.pir.md Normal file
View file

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

54
docs/content/configuration/customization/taxonomy.en.md Normal file
View file

@ -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. |

8
docs/content/configuration/customization/taxonomy.pir.md Normal file
View file

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

182
docs/content/configuration/customization/topbar/_index.en.md Normal file
View file

@ -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** | _&lt;empty&gt;_ | Mandatory reference to the page. |
| **class** | _&lt;empty&gt;_ | 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. |

9
docs/content/configuration/customization/topbar/_index.pir.md Normal file
View file

@ -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 >}}

BIN
docs/content/configuration/customization/topbar/topbar-areas.png Normal file
View file

Binary file not shown.
Side by side

After

(image error) Size: 12 KiB

BIN
docs/content/configuration/customization/topbar/topbar-closed.png Normal file
View file

Binary file not shown.
Side by side

After

(image error) Size: 7.7 KiB

38
docs/content/configuration/reference/_index.en.md Normal file
View file

@ -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" %}}
````

7
docs/content/configuration/reference/_index.pir.md Normal file
View file

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

9
docs/content/configuration/sidebar/_index.en.md Normal file
View file

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

8
docs/content/configuration/sidebar/_index.pir.md Normal file
View file

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

62
docs/content/configuration/sidebar/headerfooter/_index.en.md Normal file
View file

@ -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.

8
docs/content/configuration/sidebar/headerfooter/_index.pir.md Normal file
View file

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

BIN
docs/content/configuration/sidebar/headerfooter/home_button_defaults.png Normal file
View file

Binary file not shown.
Side by side

After

(image error) Size: 7.4 KiB

337
docs/content/configuration/sidebar/menus/_index.en.md Normal file
View file

@ -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 >}}

9
docs/content/configuration/sidebar/menus/_index.pir.md Normal file
View file

@ -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 >}}

72
docs/content/configuration/sidebar/search/_index.en.md Normal file
View file

@ -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 %}}

8
docs/content/configuration/sidebar/search/_index.pir.md Normal file
View file

@ -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 >}}

34
docs/content/configuration/sidebar/width/_index.en.md Normal file
View file

@ -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>
````

7
docs/content/configuration/sidebar/width/_index.pir.md Normal file
View file

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

9
docs/content/configuration/sitemanagement/_index.en.md Normal file
View file

@ -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 %}}

8
docs/content/configuration/sitemanagement/_index.pir.md Normal file
View file

@ -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 >}}

61
docs/content/configuration/sitemanagement/deployment/_index.en.md Normal file
View file

@ -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`.

7
docs/content/configuration/sitemanagement/deployment/_index.pir.md Normal file
View file

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

43
docs/content/configuration/sitemanagement/meta/_index.en.md Normal file
View file

@ -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.

9
docs/content/configuration/sitemanagement/meta/_index.pir.md Normal file
View file

@ -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 >}}

102
docs/content/configuration/sitemanagement/multilingual/_index.en.md Normal file
View file

@ -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 >}}

8
docs/content/configuration/sitemanagement/multilingual/_index.pir.md Normal file
View file

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

86
docs/content/configuration/sitemanagement/outputformats/_index.en.md Normal file
View file

@ -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 >}}

8
docs/content/configuration/sitemanagement/outputformats/_index.pir.md Normal file
View file

@ -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 >}}

57
docs/content/configuration/sitemanagement/stableoutput/_index.en.md Normal file
View file

@ -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 >}}

8
docs/content/configuration/sitemanagement/stableoutput/_index.pir.md Normal file
View file

@ -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 >}}

38
docs/content/configuration/sitemanagement/structure/_index.en.md Normal file
View file

@ -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.

7
docs/content/configuration/sitemanagement/structure/_index.pir.md Normal file
View file

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