nishiki/hugo-theme-relearn
1
0
Fork 0
mirror of https://github.com/McShelby/hugo-theme-relearn.git synced 2024-11-22 23:37:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: review #567

Browse source
This commit is contained in:
Sören Weber 2024-10-07 15:30:53 +02:00
parent 9a255abef9
commit 6e0ae01f14
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
68 changed files with 832 additions and 579 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
README.md
View file

@ -16,7 +16,7 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
- Responsive design for mobile devices
- Looks nice on paper (if it has to)
- Usable offline with no external dependencies
- [Usable from your local file system without a web server via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/configuration/siteorganization/deploymentscenarios/)
- [Usable from your local file system without a web server via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/deployment/)
- Integration with the [VSCode Front Matter CMS extension](https://github.com/estruyf/vscode-front-matter) for on-premise CMS capabilities
- **Customizable Appearance**
@ -38,8 +38,8 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
- [Social media integration](https://mcshelby.github.io/hugo-theme-relearn/content/image/)
- **Multilingual Support**
- [Full right-to-left (RTL) language support](https://mcshelby.github.io/hugo-theme-relearn/configuration/siteorganization/multilingual/)
- [Extensive list of supported languages](https://mcshelby.github.io/hugo-theme-relearn/configuration/siteorganization/multilingual): Arabic, Chinese (Simplified and Traditional), Czech, Dutch, English, Finnish, French, German, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Romanian, Russian, Spanish, Swahili, Turkish, Vietnamese
- [Full right-to-left (RTL) language support](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/multilingual/)
- [Extensive list of supported languages](https://mcshelby.github.io/hugo-theme-relearn/configuration/sitemanagement/multilingual): Arabic, Chinese (Simplified and Traditional), Czech, Dutch, English, Finnish, French, German, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Romanian, Russian, Spanish, Swahili, Turkish, Vietnamese
- [Multilingual content search capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search/#search-with-mixed-language-support)
- **Enhanced Markdown Features**

64
exampleSite/content/configuration/appearance/branding/_index.en.md
View file

@ -1,64 +1,62 @@
+++
description = "How to configure colors, fonts, favicon and logo"
description = "Learn how to customize your site's colors, fonts, favicon, and logo"
options = ["themeVariant"]
title = "Branding"
weight = 1
+++
The Relearn theme provides settings to change your site's colors, fonts, favicon and logo. These settings are bundled in so called color variants that are contained of a CSS file and optional configuration options in your `hugo.toml`.
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`.
The Relearn theme ships with a set of predefined color variants. You can use them as-is, copy them over and use them as a starting point for your customizations or just create completely new variants unique to your site. The [interactive variant generator](configuration/appearance/generator) may help you with this task.
You can use the pre-made variants, [customize them](#modifying-variants), or create your own. The [interactive variant generator](configuration/appearance/generator) can help you with this.
Once configured in your `hugo.toml`, you can select them with the variant selector at the bottom of the menu.
Once set up in `hugo.toml`, you can switch variants using the selector at the bottom of the menu.
## Change the Variant
## Changing the Variant
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can change the variant by setting the `themeVariant` option.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set the `themeVariant` option to change the variant.
The theme provides a recommended [advanced configuration mode](#theme-variant-advanced), combining the functionality for [multiple variants](#multiple-variants) with the possibility of [adjusting to your OS settings](#adjust-to-os-settings) and syntax highlighting and even more!
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 {#theme-variant}
### Simple Setup {#theme-variant}
#### Single Variant
Set the `themeVariant` value to the name of your theme CSS file. That's it! Your site will be displayed in this variant only.
Set `themeVariant` to your theme CSS file name:
{{< multiconfig file=hugo >}}
[params]
themeVariant = "relearn-light"
{{< /multiconfig >}}
Your theme variant file must either reside in your site's `assets/css` directory or in the similar location of the theme at `themes/hugo-theme-relearn/assets/css`. The file name must start with `theme-` and end in `.css`.
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`.
If you want to make changes to a shipped color variant, [see your choices below](#modify-shipped-variants).
#### Multiple Variants
You can also set multiple variants. 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.
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
You can also cause the site to adjust to your OS settings for light/dark mode. Just set the `themeVariant` to `auto` to become an auto mode variant. That's it.
You can use the `auto` value with the single or multiple variants option. If you are using multiple variants, you can drop `auto` at any position in the option's array, but usually it makes sense to set it in the first position and make it the default.
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. These defaults are overwritten by the first two non-auto options of your `themeVariant` option if present.
If you don't configure anything else, the theme will default to use `relearn-light` for light mode and `relearn-dark` for dark mode.
In the above example, you would end with `red` for light mode and the default of `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.
If you don't like that behavior, you can explicitly set `themeVariantAuto`. The first entry in the array is the color variant for light mode, the second for dark mode.
You can override the default with `themeVariantAuto`:
{{< multiconfig file=hugo >}}
[params]
@ -115,19 +113,19 @@ themeVariant = [
]
{{< /multiconfig >}}
## Advanced Variant Topics
## Advanced Topics
### Modify Shipped Variants
### 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 loose the ability to later easily upgrade your theme to a newer version.
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.
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.
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:
@ -141,14 +139,14 @@ In case you like a shipped variant but only want to tweak some aspects, you have
}
````
Afterwards put this in your `hugo.toml` to use your new variant:
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 but keep your modifications.
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
@ -162,19 +160,19 @@ document.addEventListener( 'themeVariantLoaded', function( e ){
## 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
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
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
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";
@ -185,18 +183,18 @@ The file must be written to `assets/css/chroma-<NAME>.css`. To use it with your
## 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
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)
## Change the Favicon
If your favicon is a 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 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 lookup the alternative filename `logo` in the same location and will repeat the search for the list of supported file types.
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:
@ -206,6 +204,6 @@ If you need to change this default behavior, create a new file `layouts/partials
## Change the Logo
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 a SVG definition!
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.

3
exampleSite/content/configuration/appearance/branding/_index.pir.md
View file

@ -1,5 +1,6 @@
+++
description = "How to configure colors, fonts, favicon and logo"
description = "Learn how to customize your site's colors, fonts, favicon, and logo"
options = ["themeVariant"]
title = "Brrrand'n"
weight = 1
+++

12
exampleSite/content/configuration/appearance/generator/_index.en.md
View file

@ -3,7 +3,7 @@ description = "An interactive tool to generate color variant stylesheets"
mermaid.force = true
options = ["themeVariant"]
title = "Stylesheet Generator"
weight = 9
weight = 3
+++
This interactive tool may help you to generate your own color variant stylesheet.
@ -11,17 +11,17 @@ 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 reflect 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 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 descendent 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.
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 heading `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`.
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**.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Once you are satisfied, you can download the new variants file and copy it into your site's `assets/css` directory. Afterwards you have to adjust the `themeVariant` option in your `hugo.toml` to your chosen file name.
Once you are satisfied, you can download the new variants file and copy it into your site's `assets/css` directory.
Eg. if your new variants file is named `theme-my-custom-variant.css`, you have to set `themeVariant='my-custom-variant'` to use it.
{{% 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/appearance/branding).
{{% /expand %}}

4
exampleSite/content/configuration/appearance/generator/_index.pir.md
View file

@ -1,6 +1,8 @@
+++
description = "An interactive tool to generate color variant stylesheets"
mermaid.force = true
options = ["themeVariant"]
title = "Stylesheet Generrrat'r"
weight = 9
weight = 3
+++
{{< piratify >}}

59
exampleSite/content/configuration/appearance/topbar/_index.en.md
View file

@ -2,22 +2,46 @@
description = "Configure the site's topbar"
options = ["breadcrumbSeparator", "disableBreadcrumb", "disableNextPrev", "disableRootBreadcrumb", "disableToc", "editURL"]
title = "Topbar"
weight = 3
weight = 2
+++
This page is about how to configure supported options for the topbar. If you want to add further buttons or functionality, [see this section](configuration/modifications/topbar).
This page is about how to configure the topbar using configuration options. If you want to add further buttons or functionality, [see this section](configuration/modifications/topbar).
Your topbar contains the following elements. Some of them are configuarable:
- {{% button style="transparent" icon="bars" %}}{{% /button %}} **sidebar**: opens the sidebar flyout if in mobile layout
- {{% button style="transparent" icon="list-alt" %}}{{% /button %}} **toc**: [opens the table of contents in an overlay](#table-of-contents)
- {{% button style="transparent" icon="empty" %}}{{% /button %}} **breadcrumb**: shows the clickable [breadcrumbs](#breadcrumbs)
- {{% button style="transparent" icon="pen" %}}{{% /button %}} **edit**: browses to the editable page if the `editURL` [parameter is set](#edit-button)
- {{% button style="transparent" icon="print" %}}{{% /button %}} **print**: browses to the chapters printable page if [print support](#print-support) was activated
- {{% button style="transparent" icon="chevron-left" %}}{{% /button %}} **prev**: browses to the [previous page](#arrow-navigation) if there is one
- {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} **next**: browses to the [next page](#arrow-navigation) if there is one
- {{% button style="transparent" icon="ellipsis-v" %}}{{% /button %}} **more**: opens the overlay if screen space is limited
## Table of Contents
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `disableToc=true` to hide the TOC button on all pages. If the button is hidden, also the keyboard shortcut is disabled. This can be overridden in a page's front matter.
{{< multiconfig file=hugo >}}
[params]
disableToc = true
{{< /multiconfig >}}
## Breadcrumbs
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `disableBreadcrumb=true` to hide the breadcrumb in the topbar.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Further, you can override the breadcrumb separator by using `breadcrumbSeparator="/"`. This separator will also be used in the breadcrumbs of the search results and taxonomy pages.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} 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 %}} `disableRootBreadcrumb=true` to remove the root breadcrumb which often feels redundant. This will also apply to the breadcrumbs of the search results and taxonomy pages.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Further, you can override the breadcrumb separator by using `breadcrumbSeparator='/'`. This separator will also be used in the breadcrumbs of the search results and taxonomy pages.
{{< multiconfig file=hugo >}}
[params]
disableBreadcrumb = true
disableRootBreadcrumb = true
breadcrumbSeparator = '/'
{{< /multiconfig >}}
## Edit Button
@ -25,27 +49,20 @@ This page is about how to configure supported options for the topbar. If you wan
The value can contain the macro `${FilePath}` which will be replaced by the file path of your displayed page. If no `${FilePath}` is given in the value, the value is treated as if the `${FilePath}` was appended at the end of the value. This can be overridden in the pages front matter.
Eg. this site is using `editURL="https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/${FilePath}"`
{{< multiconfig file=hugo >}}
[params]
editURL = 'https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/${FilePath}'
{{< /multiconfig >}}
## Print Support
You can activate print support to add the capability to print whole chapters or even the complete site. Just add the `print` output format to your home, section and page in your `hugo.toml` similar to the below:
{{< multiconfig file=hugo >}}
[outputs]
home = ["html", "rss", "print"]
section = ["html", "rss", "print"]
page = ["html", "rss", "print"]
{{< /multiconfig >}}
This will add a little printer icon in the top bar. It will switch the page to print preview when clicked. You can then send this page to the printer by using your browser's usual print functionality.
{{% notice note %}}
The resulting URL will not be [configured ugly](https://gohugo.io/templates/output-formats/#configure-output-formats) in terms of [Hugo's URL handling](https://gohugo.io/content-management/urls/#ugly-urls) even if you've set `uglyURLs=true` in your `hugo.toml`. This is due to the fact that for one mime type only one suffix can be configured.
Nevertheless, if you're unhappy with the resulting URLs you can manually redefine `outputFormats.print` in your own `hugo.toml` to your liking.
{{% /notice %}}
If you have [activated print support](configuration/sitemanagement/outputformats#print-support), a printer icon will be displayed to access the print preview.
## Arrow Navigation
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can hide the previous/next buttons by setting `disableNextPrev=true`. If the buttons are hidden, also the keyboard shortcuts are disabled.
{{< multiconfig file=hugo >}}
[params]
disableNextPrev = true
{{< /multiconfig >}}

3
exampleSite/content/configuration/appearance/topbar/_index.pir.md
View file

@ -1,6 +1,7 @@
+++
description = "Configure the site's topbar"
options = ["breadcrumbSeparator", "disableBreadcrumb", "disableNextPrev", "disableRootBreadcrumb", "disableToc", "editURL"]
title = "Topbarrr"
weight = 3
weight = 2
+++
{{< piratify >}}

22
exampleSite/content/configuration/content/headings/index.en.md
View file

@ -1,18 +1,28 @@
+++
description = "How to configure heading anchors"
description = "Configuring heading anchors"
options = ["disableAnchorCopy", "disableAnchorScrolling"]
title = "Headings"
weight = 2
+++
Each heading may have an anchor link that is displayed when the heading is hovered.
Headings can have anchor links that appear when you hover over them.
The behavior what should happen if the anchor icon is clicked is configurable in your `hugo.toml`. By default all of the following options are activated. If you deactivate all options, no anchor icon will be shown on hover.
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 to Clipboard
## Copy Anchor Links
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} If you set `disableAnchorCopy=true`, no anchor link will be copied to the clipboard when the anchor icon is pressed.
{{% 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 %}} If you set `disableAnchorScrolling=true`, the page will not scroll to the beginning of the heading when the anchor icon is clicked.
{{% 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 >}}

3
exampleSite/content/configuration/content/headings/index.pir.md
View file

@ -1,5 +1,6 @@
+++
description = "How to configure heading anchors"
description = "Configuring heading anchors"
options = ["disableAnchorCopy", "disableAnchorScrolling"]
title = "Headings"
weight = 2
+++

35
exampleSite/content/configuration/content/hidden/_index.en.md
View file

@ -1,29 +1,44 @@
+++
description = "Learn about the hiddes pages feature"
description = "Learn about the hidden pages feature"
frontmatter = ["hidden"]
options = ["disableSearchHiddenPages", "disableSeoHiddenPages", "disableTagHiddenPages"]
title = "Hidden Pages"
weight = 4
+++
The theme provides the concept of hidden pages.
This theme allows you to create hidden pages.
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} While Hugo has the `draft` option to not create a page at all, a hidden page is created but not shown in the navigation. Just set `hidden=true` in your pages front matter. This can be useful if you want to have a page that is only accessible via a link.
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Hidden pages are created but not shown in the navigation. To make a page hidden, set `hidden=true` in its front matter. This is useful for pages you only want to access via a direct link.
If you access a hidden page via its URL, it will be revealed in the navigation menu.
When you visit a hidden page's URL, it will appear in the navigation menu.
Hidden pages can even contain hidden subpages.
Hidden pages can also have hidden subpages.
By default, a hidden page is only hidden from a human user of your site. Crawlers may still see the URLs advertised in the sitemap, etc. You can avoid this by the following options
By default, hidden pages are only hidden from human visitors. Search engines can still find them by crawling your site. You can prevent this with these options:
## Hide from Search
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} To hide hidden pages from search results of the search popup and dedicated search page, set `disableSearchHiddenPages=true`.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} To remove hidden pages from search results, use `disableSearchHiddenPages=true`.
## Hide from Crawlers
{{< multiconfig file=hugo >}}
[params]
disableSearchHiddenPages = true
{{< /multiconfig >}}
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} To hide hidden pages from crawlers by removing links from the sitemap and rss feed, set `disableSeoHiddenPages=true`.
## 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 hide hidden pages from showing up on the taxonomy and term pages, set `disableTagHiddenPages=true`. If this reduces term counters to zero, an empty but unlinked term page will be created anyhow.
{{% 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 >}}

4
exampleSite/content/configuration/content/hidden/_index.pir.md
View file

@ -1,5 +1,7 @@
+++
description = "Learn about the hiddes pages feature"
description = "Learn about the hidden pages feature"
frontmatter = ["hidden"]
options = ["disableSearchHiddenPages", "disableSeoHiddenPages", "disableTagHiddenPages"]
title = "Hidden Pages"
weight = 4
+++

45
exampleSite/content/configuration/content/layouts/index.en.md
View file

@ -1,30 +1,37 @@
+++
description = "How to use and extend layouts"
description = "Using and extending layouts"
title = "Custom Layouts"
weight = 3
+++
The Relearn theme provides a few layouts for you to use. Namely these are `home`, `chapter` and `default`. All are accessible as so called [archetypes](content/layouts) for an author of your site.
The Relearn theme offers several layouts: `home`, `chapter`, and `default`. These are available as [archetypes](content/layouts) for site authors.
You can manually use them by defining the `type` option accordingly in your page's front matter.
To use a layout, set the `type` option in your page's front matter.
These layouts will use the general framework of the theme as defined in `themes/hugo-theme-learn/layouts/_default/baseof.html` but be modify the appearance of the content inside of the page.
These layouts use the theme's framework from `themes/hugo-theme-learn/layouts/_default/baseof.html`, containing the topbar and sidebar but change how content appears in the center of the page.
### Defining Layouts
### Creating Your Own Layout
To provide your own custom layout, you need to choose a name, say `mylayout`. Create a file `layouts/mylayout/views/article.html` with the following content
To make a custom layout:
````html {title="layouts/mylayout/views/article.html"}
<article class="mylayout">
<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>
````
1. Choose a name (for example, `mylayout`)
2. Create a file at `layouts/mylayout/views/article.html`
3. Add this content
In this file, you can do what ever you want. Usually, you want to at least set some `class` identifier to add custom CSS styles for your layout and call the partial `article-content.html` to render the content of your page.
````html {title="layouts/mylayout/views/article.html"}
<article class="mylayout">
<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>
````
In this file, you can customize the layout as needed. Typically, you'll want to:
- Set a `class` at the `article` element for custom CSS styles
- Use `{{ partial "article-content.html" . }}` to show your page content

2
exampleSite/content/configuration/content/layouts/index.pir.md
View file

@ -1,5 +1,5 @@
+++
description = "How to use and extend layouts"
description = "Using and extending layouts"
title = "Custom Layouts"
weight = 3
+++

14
exampleSite/content/configuration/content/width/_index.en.md
View file

@ -1,23 +1,23 @@
+++
description = "Changing the width the content area"
description = "Changing the content area width"
title = "Width"
weight = 1
+++
The theme reacts to browser resizes and adjusts the menu and content width accordingly.
The theme adjusts the content width when you resize your browser.
If you dislike the default behavior, you can link to a CSS stylesheet or change it in your `layouts/partials/custom-header.html`.
If you want to change the chosen default width, you can add CSS variables to `layouts/partials/custom-header.html`.
## Change the Main Area's Max Width
## Changing the Main Area's Maximum Width
By default the main area width will only grow to a certain extent if more vertical screen space is available. This is done for readability purposes as long lines are usually harder to read.
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
If you are unhappy with the default, you can define the following CSS variable and set the value to your liking. If you want to use all available space, select a really big value like `1000rem`;
For full width, use a large value like `1000rem`.
````html {title="layouts/partials/custom-header.html"}
<style>
:root {
--MAIN-WIDTH-MAX: 80.25rem;
--MAIN-WIDTH-MAX: 1000rem;
}
</style>
````

4
exampleSite/content/configuration/content/width/_index.pir.md
View file

@ -1,6 +1,6 @@
+++
description = "Changing the width of menu and content area"
title = "Page Width"
description = "Changing the content area width"
title = "Width"
weight = 1
+++
{{< piratify >}}

45
exampleSite/content/configuration/modifications/dependencies/_index.en.md
View file

@ -1,33 +1,33 @@
+++
description = "Add further code to your site"
options = ["relearn.dependencies"]
title = "Extending HTML"
title = "Extending Scripts"
weight = 2
+++
One of the most commonly asked questions is, how to add additional CSS styles or JavaScript.
A common question is how to add extra CSS styles or JavaScript to your site. This depends on what you need.
This depends on your use case.
## Adding JavaScript or Stylesheets to All Pages
## Adding JavaScript or Stylesheets Unconditionally
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`.
If you simply want to add additional JavaScript files or CSS stylesheets on every page of your site, you can do so by either adding them in your `layouts/partials/custom-header.html` or `layouts/partials/custom-footer.html` partial.
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.
Sometimes this just bloats up your site when only in a few cases those files are really needed. See the [next section](#own-shortcodes-with-dependencies), on how to conditionally add such dependencies.
## Custom Shortcodes with Dependencies
## Own 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.
Certain shortcodes make use of additional dependencies like JavaScript and CSS files. The theme only loads these dependencies if the shortcode is used. To do so correctly the theme adds management code in various files.
For example, to create a shortcode called `myshortcode` that needs the `jquery` library:
You can you use this mechanism in your own shortcodes. Say you want to add a shortcode `myshortcode` that also requires the `jquery` JavaScript library.
1. Write the shortcode file `layouts/shortcodes/myshortcode.html` and add the following line
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 }}
...
{{- .Page.Store.Set "hasMyShortcode" true }}
...
````
1. {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Add the following snippet to your `hugo.toml`
2. {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Add this to your `hugo.toml`:
{{< multiconfig file=hugo >}}
[params.relearn.dependencies]
@ -35,10 +35,7 @@ You can you use this mechanism in your own shortcodes. Say you want to add a sho
name = "MyShortcode"
{{< /multiconfig >}}
1. Add the dependency loader file `layouts/partials/dependencies/myshortcode.html`. The loader file will be called from multiple locations inside of the theme with the parameter `page` containing the current [page](https://gohugo.io/methods/page/) variable and `location` with one of the currently defined locations
* `header`: if called at the end of the HTML `head` element
* `footer`: if called at the end of the HTML `body` element
3. Create loader file `layouts/partials/dependencies/myshortcode.html`:
````go {title="layouts/partials/dependencies/myshortcode.html"}
{{- if eq .location "footer" }}
@ -46,18 +43,20 @@ You can you use this mechanism in your own shortcodes. Say you want to add a sho
{{- end }}
````
Character casing is relevant!
Important notes:
- the `name` setting in your `hugo.toml` must match the key (that needs to be prefixed with a `has`) you used for the store in your `layouts/shortcodes/myshortcode.html`.
- the key on `relearn.dependencies` in your `hugo.toml` must match the base file name of your loader file.
- 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.
See the `math`, `mermaid`, and `openapi` shortcodes for examples.
{{% notice note %}}
If you are really into customization of the theme and want to use the dependency loader for your own locations, you can do this by simply calling it from inside of your overriden partials
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.

3
exampleSite/content/configuration/modifications/dependencies/_index.pir.md
View file

@ -1,6 +1,7 @@
+++
description = "Add further code to your site"
title = "Extending HTML"
options = ["relearn.dependencies"]
title = "Extending Scripts"
weight = 2
+++
{{< piratify >}}

104
exampleSite/content/configuration/modifications/imageeffects.en.md
View file

@ -1,27 +1,17 @@
+++
description = "How to extend image effects"
frontmatter = ["imageEffects"]
options = ["imageEffects"]
title = "Custom Image Effects"
weight = 3
+++
The theme supports non-standard [image effects](content/markdown#image-effects).
This page shows you, how to configure custom [image effects](content/markdown#image-effects) on top of existing ones.
| Name | Description |
| -------- | ----------------------------------------------------------------- |
| border | Draws a light thin border around the image |
| lazy | Lets the image be lazy loaded |
| lightbox | The image will be clickable to show it enlarged |
| shadow | Draws a shadow around the image to make it appear hovered/glowing |
For a detailed usage example, see [this page](content/imageeffects).
As [described](content/markdown#image-effects), you can add this to the URL query parameter, but this may be cumbersome to be done consistently for the whole page. Instead, you can configure the defaults in your `hugo.toml` as well as overriding these default in the pages front matter.
If you don't configure anything in your `hugo.toml`, the image effects default to
Explicitly set URL query parameter will override the defaults in effect for a page or your site.
Without any settings in your `hugo.toml` `imageEffects` defaults to
{{< multiconfig file=hugo >}}
{{< multiconfig >}}
[params]
[params.imageEffects]
border = false
@ -30,50 +20,76 @@ Without any settings in your `hugo.toml` `imageEffects` defaults to
shadow = false
{{< /multiconfig >}}
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} This can be overridden in a pages front matter by eg.
You can change these settings in your `hugo.toml`
{{< multiconfig fm=true >}}
[imageEffects]
border = true
{{< multiconfig file=hugo >}}
[params]
[params.imageEffects]
border = true
lazy = false
{{< /multiconfig >}}
Or by explicitly override settings by URL query parameter
````md {title="URL"}
![Minion](https://octodex.github.com/images/minion.png?lightbox=false&bg-white=true)
````
The settings applied to the above image would be
This would result in
{{< multiconfig >}}
border = true
lazy = true
lightbox = false
shadow = false
bg-white = true
[params]
[params.imageEffects]
border = true
lazy = false
lightbox = true
shadow = false
{{< /multiconfig >}}
This ends up in the following HTML where the parameter are converted to CSS classes.
## Adding Custom Effects
````html {title="HTML"}
<img src="https://octodex.github.com/images/minion.png?lightbox=false&bg-white=true" loading="lazy" alt="Minion" class="bg-white border lazy nolightbox noshadow">
````
## Extending
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} As you can see in the above example, the `bg-white` parameter is not initially supported in the themes default settings. The theme allows you to define arbitrary parameter by just adding them to the URL query parameter or set them in your page's front matter or `hugo.toml`.
You can add new effects with boolean values
{{< multiconfig file=hugo >}}
[params]
[params.imageEffects]
bg-white = true
border = false
lazy = true
{{< /multiconfig >}}
Result:
{{< multiconfig >}}
[params]
[params.imageEffects]
bg-white = true
border = true
lazy = false
lightbox = true
shadow = false
{{< /multiconfig >}}
{{% notice note %}}
If no extended parameter like `bg-white` in the example is set on the URL, a `class="nobg-white"` in the HTML will only be generated if a default value was set in the page's front matter or `hugo.toml` .
{{% /notice %}}
## Styling Custom Effects
If the effective image effect value is
- `true`: add a class with the effect's name
- `false`: add a class with the effect's name and a "no" prefix
### Example
````markdown
![Minion](https://octodex.github.com/images/minion.png)
````
### Result
````html
<img src="https://octodex.github.com/images/minion.png" loading="lazy" alt="Minion" class="bg-white border nolazy lightbox noshadow">
````
Styles for default image effets are contained in the theme. Add custom styles for your extension image effects to `layouts/partials/content-header.html`.
In the above example you could add styles for both cases:
````css
img.bg-white {
background-color: white;
}
img.nobg-white {
background-color: transparent;
}
````

1
exampleSite/content/configuration/modifications/imageeffects.pir.md
View file

@ -1,5 +1,6 @@
+++
description = "How to extend image effects"
options = ["imageEffects"]
title = "Custom Image Effects"
weight = 3
+++

27
exampleSite/content/configuration/modifications/outputformats/_index.en.md
View file

@ -4,21 +4,26 @@ title = "Custom Output Formats"
weight = 5
+++
Besides the `print` output format supoorted by the theme, you can write your own [output formats](https://gohugo.io/templates/output-formats/).
In addition to the [output formats coming with the theme](configuration/sitemanagement/outputformats), you can create your own [output formats](https://gohugo.io/templates/output-formats/).
## From Scratch
## Starting from Scratch
Suppoe you want to add a new output format `myformat` that outputs HTML. You want to ignore everything the theme provides and implement the whole format by yourself.
If you want to add a new output format called `myformat` that outputs HTML and you want to build everything yourself without using the theme's components:
For that, add a file `layouts/_default/baseof.myformat.html` and implement everything from scratch.
1. Create a file `layouts/_default/baseof.myformat.html`
2. Implement all the necessary code in this file
## Using the Theme's Frame
## Using the Theme's Structure
If you want to keep the general framework and want to change only aspects of it, you can override some of following files
If you want to keep the general framework and only change specific parts, you can override these files:
- `layouts/_default/views/article.html` - how one page content, including the title heading should be displayed
- `layouts/_default/views/body.html` - how the body of the page should be composed; usually you either call `bodys/single.html` to show a single page's content or `bodys/tree.html` to show the page's content and the content of every subpages recursivley
- `layouts/_default/views/menu.html` - how the sidebar menu should be assembled
- `layouts/_default/views/storeOutputFormat.html` - this stores the name of the output format in a variable to later be used by the framework; this makes it possible to write CSS specific to your output format
- `layouts/_default/views/article.html`: Controls how a page's content and title are displayed
- `layouts/_default/views/body.html`: Determines the page body structure
- `layouts/_default/views/menu.html`: Defines the sidebar menu layout
- `layouts/_default/views/storeOutputFormat.html`: Stores the output format name for use in the framework
For an live example, see the implementations for the shipped `print` output format, that overrides [`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) and [`layouts/_default/views/storeOutputFormat.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/storeOutputFormat.print.html).
For a real-world example, check out the `print` output format implementations
- [`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)

36
exampleSite/content/configuration/modifications/partials/index.en.md
View file

@ -6,40 +6,40 @@ weight = 1
## Customizable Partials
The Relearn theme has been built to be as configurable as possible by defining multiple partials that can be overridden by you to customize the theme.
The Relearn theme allows you to customize various parts of the theme by overriding partials. This makes the theme highly configurable.
As a rule of thumb, the less code a partial of the theme contains, the less likely you will have trouble updating the theme to a future version.
A good rule to follow: The less code a partial contains, the easier it will be to update the theme in the future.
Following is a list of partials that are save to be overridden
Here's a list of partials you can safely override:
- `layouts/partials/content.html`: the content of a page itself, can be overridden if you want to display page's meta data above or below the content
- `layouts/partials/content.html`: The main content of a page. Override this to display additonal page metadata.
- `layouts/partials/content-header.html`: header above the title, has a default implementation to display the tags taxonomy but you can override it if you don't like it
- `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`: footer below the content, has a default implementation to display author information, modification dates and category taxonomy but you can override it if you don't like it
- `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`: custom headers in page; meant to be overridden when adding CSS imports; don't forget to include `style` HTML tag directive in your file
- `layouts/partials/custom-header.html`: For adding custom CSS. Remember to include the `style` HTML tag.
- `layouts/partials/custom-footer.html`: custom footer in page; meant to be overridden when adding JavaScript; don't forget to include `javascript` HTML tag directive in your file
- `layouts/partials/custom-footer.html`: For adding custom JavaScript. Remember to include the `script` HTML tag.
- `layouts/partials/favicon.html`: the favicon; definitely meant to be overridden
- `layouts/partials/favicon.html`: The favicon. You should definitely customize this.
- `layouts/partials/heading.html`: the pages title headings
- `layouts/partials/heading.html`: the page's title headings
- `layouts/partials/heading-pre.html`: prepend something to pages title headings; if you override this, it is your responsibility to take the page's `headingPre` setting into account
- `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`: append something to pages title headings; if you override this, it is your responsibility to take the page's `headingPost` setting into account
- `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 on the top left corner; definitely meant to be overridden
- `layouts/partials/logo.html`: The logo in the top left corner. You should customize this.
- `layouts/partials/menu-pre.html`: prepend something to a menu item; if you override this, it is your responsibility to take the page's `menuPre` setting into account
- `layouts/partials/menu-pre.html`: Add content before menu items. Remember to consider the `menuPre` front matter.
- `layouts/partials/menu-post.html`: append something to a menu item; if you override this, it is your responsibility to take the page's `menuPost` setting into account
- `layouts/partials/menu-post.html`: Add content after menu items. Remember to consider the `menuPost` front matter.
- `layouts/partials/menu-footer.html`: footer of the left menu
- `layouts/partials/menu-footer.html`: The footer of the left menu.
You may override other partials from the directory `themes/hugo-relearn-themes/` besides `themes/hugo-relearn-themes/layouts/partials/_relearn`. Just be aware that this may become a hassle with future updates.
You can override other partials from `themes/hugo-relearn-themes/`, but be careful as this might make future updates more difficult.
## Usable Partials
You may use other partials from the directory `themes/hugo-relearn-themes/` besides the ones contained in `themes/hugo-relearn-themes/layouts/partials/_relearn`. Just be aware that using other partials besides [the ones mentioned above](#customizable-partials) may become a hassle with future updates.
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 above might make future updates more challenging.

23
exampleSite/content/configuration/modifications/taxonomy.en.md
View file

@ -6,23 +6,22 @@ title = "Custom Taxonomies"
weight = 6
+++
This page shows you how customize your templates to display custom taxonomies on your pages.
This page explains how to show custom taxonomies on your pages.
See the official documentation on [how to configure custom taxnomies](https://gohugo.io/content-management/taxonomies/#configure-taxonomies) and [how to use them in your page's front matter](https://gohugo.io/content-management/taxonomies/#assign-terms-to-content).
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).
## Standard Behavior
## Default Behavior
The Relearn theme displays Hugo's [default taxonomies](https://gohugo.io/content-management/taxonomies/#default-taxonomies) _tag_ and _category_ out of the box.
The Relearn theme automatically shows Hugo's [default taxonomies](https://gohugo.io/content-management/taxonomies/#default-taxonomies) _tags_ and _categories_ out of the box.
The _tags_ are displayed at the top of the page in alphabetical order.
- 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.
The _categories_ are displayed at the bottom of the page in alphabetical order.
Each item links to a page showing all articles with that term.
Each item is a link to a taxonomy page displaying all the articles with the given term.
## Setting Up Custom Taxonomies
## Configuration
To add custom taxnomies, you have to configure them in your `hugo.toml` and also have to add the default taxonomies if you want to use them.
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]
@ -31,9 +30,9 @@ To add custom taxnomies, you have to configure them in your `hugo.toml` and also
tag = 'tags'
{{< /multiconfig >}}
## Customization
## Showing Custom Taxonomies
You can display the terms of your custom taxonomy somewhere in your page (often in the `layouts/partials/content-footer.html`) by calling a partial that does the job for you
To display your custom taxonomy terms, add this to your page (usually in `layouts/partials/content-footer.html`):
````go
{{ partial "term-list.html" (dict

57
exampleSite/content/configuration/modifications/topbar/_index.en.md
View file

@ -7,9 +7,9 @@ weight = 4
The theme comes with a reasonably configured topbar. You can learn how to [configure the defaults in this section](configuration/appearance/topbar).
![Topbar on mobile devices](topbar-closed.png)
![topbar on mobile devices](topbar-closed.png)
Nevertheless, your requirements may differ from this configuration. Luckily the theme got you covered as the topbar, its buttons and the functionality behind these buttons is fully configurable by you.
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.
@ -19,22 +19,22 @@ All mentioned file names below can be clicked and show you the implementation fo
The default configuration comes with three predefined areas that may contain an arbitrary set of buttons.
![Topbar with default areas marked](topbar-areas.png)
![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 can not add additional areas in the topbar, you are free to configure additional buttons that behave like the _more_ button, providing further user defined areas.
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)
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
- {{% 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](configuration/options)
- {{% 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 chapters printable page if [print support](configuration/appearance/topbar#print-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/appearance/topbar#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 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 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
@ -43,9 +43,9 @@ Not all buttons are displayed at every given time. This is configurable (see bel
## Redefining Areas
Each predefined area and button comes in their own file. By that it is easy for you to overwrite an area file in your installation reusing only the buttons you like.
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.
Eg. 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.
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.
@ -56,20 +56,20 @@ The below example sets an explicit value for the `onempty` parameter, overriding
)}}
````
## Defining own Buttons
## 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
- [**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:
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
@ -79,19 +79,19 @@ 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`; eg. this is used to move buttons to the _more_ area overlay in the mobile layout
- `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.
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`.
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 displayed in disabled state if the overlay is empty
- `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.
@ -112,15 +112,15 @@ For displaying an area in the button's overlay, see [Area-Button](#area-button).
|-----------------------|-----------------|-------------|
| **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 disabled state regardless of its **content** |
| **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 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`. |
| **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. |
| **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
@ -135,8 +135,8 @@ Call this from your own button templates if you want to implement a button with
| **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 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`. |
| **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. |
@ -148,16 +148,16 @@ The predefined buttons by the theme (all other buttons besides the _more_ and _t
Call these from your own redefined area templates if you want to use default button behavior.
The `<varying>` parameter values are different for each button and configured for standard behavior as seen on this page.
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. |
| **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
@ -165,15 +165,14 @@ The predefined buttons by the theme that open an overlay (the _more_ and _toc_ b
Call these from your own redefined area templates if you want to use default button behavior utilizing overlay functionality.
The `<varying>` parameter values are different for each button and configured for standard behavior as seen on this page.
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 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`. |
| **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. |

1
exampleSite/content/configuration/modifications/topbar/_index.pir.md
View file

@ -1,5 +1,6 @@
+++
description = "How to extend the topbar"
options = ["editURL"]
title = "Custom Topbarrr"
weight = 4
+++

12
exampleSite/content/configuration/options/_index.en.md
View file

@ -1,17 +1,17 @@
+++
description = "All configuration options of the Relearn theme"
description = "Configuration options for the Relearn theme"
tags = ["reference"]
title = "Options Reference"
weight = 6
+++
You can set configuration options in your `hugo.toml`.
This page explains how to configure the Relearn theme in your `hugo.toml` file.
On top of [Hugo's configuration options](https://gohugo.io/getting-started/configuration/#all-configuration-settings), you can use the additional theme settings listed below.
In addition to [Hugo's standard options](https://gohugo.io/getting-started/configuration/#all-configuration-settings), the Relearn theme offers extra settings listed here.
A configuration option provided by the theme is marked with a {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} badge throughout the documentation.
Throughout the documentation, theme-specific options are marked with a {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} badge.
You set each theme configuration option in the `params` section of your `hugo.toml`. For example, setting `math`
Add theme options to the `params` section of your `hugo.toml`. For example:
{{< multiconfig file=hugo >}}
[params]
@ -24,7 +24,7 @@ You set each theme configuration option in the `params` section of your `hugo.to
## All Configuration Options
The example reflect example values. The defaults can be taken from the [annotated example](#annotated-configuration-options) below or the individual documentation.
Here's a list of all available options with example values. Default values are described in the [annotated example][annotated example](#annotated-configuration-options) below in each option's documentation.
{{< multiconfig file=hugo section=params >}}
{{% include "config/_default/params.toml" %}}

2
exampleSite/content/configuration/options/_index.pir.md
View file

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

61
exampleSite/content/configuration/sidebar/headerfooter/_index.en.md
View file

@ -1,41 +1,52 @@
+++
description = "Configure the header and footer of the sidebar"
options = ["disableLandingPageButton", "showVisitedLinks"]
options = ["disableLandingPageButton", "landingPageName", "showVisitedLinks"]
title = "Header & Footer"
weight = 2
+++
## Home Button Configuration
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} If `disableLandingPageButton=true`, the Home button will be hidden on the left menu.
If you display the Home button, it is an alternative for clicking on the logo. To edit its logo or text, you will have to configure the `landingPageName` for the 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 is not configured for a specific language, they will get their default values of
{{< multiconfig >}}
[params]
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
{{< /multiconfig >}}
The home button is going to look like this:
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 >}}
[params]
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
{{< /multiconfig >}}
## History
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `showVisitedLinks=true` to show checkmarks for visited pages of the main menu. This also causes the display of the `Clear History` entry in the lower part of the menu to remove all checkmarks. The checkmarks will also been removed if you regenerate your site as the used ids are not stable.
{{% 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 >}}
[params]
showVisitedLinks = true
{{< /multiconfig >}}
## Footer
You can change the menu footer by overriding the partial `layouts/partials/menu-footer.html`. See the [Partials section](configuration/modifications/partials) for more customization options.
To change the menu footer, edit the `layouts/partials/menu-footer.html` file. Check out the [Partials section](configuration/modifications/partials) for more ways to customize your site.

1
exampleSite/content/configuration/sidebar/headerfooter/_index.pir.md
View file

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

35
exampleSite/content/configuration/sidebar/navigationmenu/_index.en.md
View file

@ -5,32 +5,43 @@ title = "Navigation Menu"
weight = 4
+++
The navigation menu is automatically generated from [your content files](content/organization).
The navigation menu is automatically created from [your content files](content/organization).
You can define certain settings globally in your `hugo.toml`. These are inherited to all pages as their default values but can be overwritten in their front matter.
All configurations options apply to all pages but can be changed in each page's front matter.
## Expand State of Nested Sections
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Use `alwaysopen` to set the initial expand state of submenus. This controls whether submenus will be expanded (`true`), or collapsed (`false`) in the menu. If not set, the first menu level is set to false, all others levels are set to true.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Use `alwaysopen` to control how submenus appear. Set it to `true` to expand submenus, or `false` to collapse them. If not set, the first menu level is collapsed, and all others are expanded.
This can be overridden individually for each page in its front matter.
{{< multiconfig file=hugo >}}
[params]
alwaysopen = true
{{< /multiconfig >}}
If the _displayed_ page has submenus, they will always been displayed expanded regardless of this option.
The current page's submenus are always expanded, regardless of this setting.
## Expander for Nested Sections
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `collapsibleMenu=true` to show an expander for submenus. If set to `true`, submenus in the sidebar will be displayed as collapsible trees and a clickable expander is set in front of those entries.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `collapsibleMenu=true` to add an expander for submenus. This shows submenus as collapsible trees with a clickable expander.
{{< multiconfig file=hugo >}}
[params]
collapsibleMenu = true
{{< /multiconfig >}}
> [!WARNING]
> Setting this option to `true` may cause your build to significantly slow down and degrade built performance, depending on your machine and the amount of pages.
> Using this option may slow down your build process, especially with many pages.
>
> We've observed this with 1000+ pages with a built time of around 2min. With 5000+ pages it was unbearable slow taking the built half an hour to complete.
>
> This is because for each page being added, every other pages needs to be visited once. This results in quadratic built time. In an already slow environment, adding just one single new page may result in unbearable built times afterwards.
> We've seen builds taking 2 minutes with 1000+ pages, and over 30 minutes with 5000+ pages.
>
> This happens because each new page affects all other pages, leading to exponentially longer build times.
## Default Sort By
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Set `ordersectionsby` to set the sorting criterium of navigation menus. Defaults to `weight`. Menus can be ordered by `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length` or `default` (adhering to Hugo's default sort order).
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Use `ordersectionsby` to choose how navigation menus are sorted. The default is `weight`. You can sort by `weight`, `title`, `linktitle`, `modifieddate`, `expirydate`, `publishdate`, `date`, `length`, or `default` (Hugo's standard order).
This can be overridden individually for each page in its front matter.
{{< multiconfig file=hugo >}}
[params]
ordersectionsby = 'weight'
{{< /multiconfig >}}

1
exampleSite/content/configuration/sidebar/navigationmenu/_index.pir.md
View file

@ -1,5 +1,6 @@
+++
description = "Default behavior of the navigation menu"
options = ["alwaysopen", "collapsibleMenu", "ordersectionsby"]
title = "Navigation Menu"
weight = 4
+++

56
exampleSite/content/configuration/sidebar/search/_index.en.md
View file

@ -7,56 +7,64 @@ weight = 3
## Configure Search
The theme comes with three levels of search, all provided through the search form in the menu
The theme offers three levels of search through the menu's search form:
- in-page search: a search term will be marked if found in the currently displayed page
- search popup: a popup will open during typing if the term is found in other pages of your site
- dedicated search page: you can access a dedicated search page by either clicking on the magnifier glass or by typing and pressing <kbd>ENTER</kbd>
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 depends on the previous level to be enabled, eg. the dedicated search page is only available, if you have search popup and in-page search enabled. If no search level is configured, the search form will not be displayed.
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 %}} By default all three levels are enabled. You can disable each level by the following settings in your `hugo.toml`:
{{%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`
- In-page search: `disableSearch=true`
- Search popup: `disableSearchIndex=true`
- Dedicated search page: `disableSearchPage=true`
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default the following files will be created, relative to each languages home page but can be overwritten:
{{< multiconfig file=hugo >}}
[params]
disableSearch = true
disableSearchIndex = true
disableSearchPage = true
{{< /multiconfig >}}
- search popup: `searchindex.js`, configured by `searchIndexURL`
- dedicated search page: `search/index.html`, configured by `searchPageURL`
{{%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 = 'mysearchindex.js'
searchPageURL = 'megasearch'
{{< /multiconfig >}}
{{% notice note %}}
You only need to reconfigure the file / page URLs if you have own content at those URLs in your project. Eg. this can happen if you set `uglyURLs=true` in your `hugo.toml` and defining a Markdown file `content/search.md`.
Only change these if you have content at those URLs. This can happen with `uglyURLs=true` in `hugo.toml` and having a content file at `content/search.md`.
To make sure, there is no duplicate content for any given URL of your project, run `hugo --printPathWarnings`.
Check for duplicate URLs by running `hugo --printPathWarnings`.
{{% /notice %}}
## Supported Languages
In case each page's content is written in one single language only, the above configuration will already configure the site's search functionality correctly.
{{% notice warning %}}
Although the theme supports a wide variety of languages, the site's search via the [Lunr](https://lunrjs.com) search library does not.
You'll see error reports in your browsers console log for each unsupported language. Currently unsupported are:
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
- Polish
- Swahili
{{% /notice %}}
### Search with Mixed Language Support
## Mixed Language Support
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} In case your page's content contains text in multiple languages (e.g. you are writing a Russian documentation for your English API), you can set those languages in `additionalContentLanguage` to broaden the search.
{{%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 >}}
As this is an array, you can add multiple additional languages.
You can add multiple languages to this array.
{{% notice note %}}
Keep in mind that the language code required here, is the base language code. E.g. if you have additional content in `zh-CN`, you have to add just `zh` to this parameter.
Use the base language code. For example, if your page is using `zh-CN`, add `zh` to this parameter.
{{% /notice %}}

1
exampleSite/content/configuration/sidebar/search/_index.pir.md
View file

@ -1,5 +1,6 @@
+++
description = "Configure search and the search form"
options = ["additionalContentLanguage", "disableSearch", "disableSearchIndex", "disableSearchPage", "searchIndexURL", "searchPageURL"]
title = "Search"
weight = 3
+++

37
exampleSite/content/configuration/sidebar/shortcutmenu/_index.en.md
View file

@ -5,24 +5,31 @@ title = "Shortcut Menu"
weight = 5
+++
The sidebar contains the navigation menu of your content files but you can also add additional menu entries or shortcuts below the navigation menu.
The sidebar contains your content's navigation menu, but you can also add extra menu entries or shortcuts in a separate section.
Be sure to use the `pageRef` property instead of `url` for all links internal to your site. You can read more about [Hugo's menu configuration](https://gohugo.io/content-management/menus/#define-in-site-configuration) in its documenation.
For internal links, use the `pageRef` property instead of `url`. Learn more about [Hugo's menu configuration](https://gohugo.io/content-management/menus/#define-in-site-configuration).
## Title
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, the shortcut menu is preceded by a title ("_More_" in the english translation). This title can be disabled by setting `disableShortcutsTitle=true`. However, if you want to keep the title but change its value, it can be overridden by changing your local i18n translation string configuration.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} By default, the shortcut menu has a title ("_More_" in English).
For example, in your local `i18n/en.toml` file, add the following content
You can disable this title with `disableShortcutsTitle=true`.
````toml {title="en.toml"}
{{< multiconfig file=hugo >}}
[params]
disableShortcutsTitle = true
{{< /multiconfig >}}
To change the title, update your local i18n translation file.
````toml {title="i18n/en.toml"}
[Shortcuts-Title]
other = "Other Great Stuff"
````
## Single Language Example
Edit the `hugo.toml` and add a `[[menu.shortcuts]]` entry for each link your want to add.
Edit `hugo.toml` and add `[[menu.shortcuts]]` entries for each link:
{{< multiconfig file=hugo >}}
[[menu.shortcuts]]
@ -55,7 +62,7 @@ Edit the `hugo.toml` and add a `[[menu.shortcuts]]` entry for each link your wan
## Multilingual Example
When using a multilingual website, you can set different menus for each language. In the `hugo.toml` file, prefix your menu configuration by `Languages.<language-id>`.
For multilingual sites, set different menus for each language in `hugo.toml`:
{{< multiconfig file=hugo >}}
[languages]
@ -63,8 +70,6 @@ When using a multilingual website, you can set different menus for each language
title = "Hugo Relearn Theme"
weight = 1
languageName = "English"
[languages.en.params]
landingPageName = "<i class='fa-fw fas fa-home'></i> Home"
[[languages.en.menu.shortcuts]]
name = "<i class='fa-fw fab fa-github'></i> GitHub repo"
@ -95,10 +100,8 @@ When using a multilingual website, you can set different menus for each language
[languages.pir]
title = "Cap'n Hugo Relearrrn Theme"
weight = 1
weight = 2
languageName = "Arrr! Pirrratish"
[languages.pir.params]
landingPageName = "<i class='fa-fw fas fa-home'></i> Arrr! Home"
[[languages.pir.menu.shortcuts]]
name = "<i class='fa-fw fab fa-github'></i> GitHub repo"
@ -128,11 +131,11 @@ When using a multilingual website, you can set different menus for each language
weight = 40
{{< /multiconfig >}}
## How to Display Pages Only in the Shortcuts Menu
## Displaying Pages Only in the Shortcuts Menu
If you have shortcuts to pages inside of your project and you don't want them to show up in your navigation menu, you have two choices:
To show pages only in the shortcuts menu you have two choices
1. Make the page file for the shortcut a [headless branch bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle) (contained in its own subdirectory and called `_index.md`) and add the following front matter configuration to the file (see exampleSite's `content/showcase/_index.en.md`). This causes its content to **not** be contained in the sitemap.
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"
@ -142,7 +145,7 @@ If you have shortcuts to pages inside of your project and you don't want them to
publishResources = true
{{< /multiconfig >}}
2. Store the page file for the shortcut below a parent headless branch bundle and add the following front matter to he **parent** (see exampleSite's `content/more/_index.en.md`). **Don't give this page a `title`** as this will cause it to be shown in the breadcrumbs - a thing you most likely don't want.
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]
@ -151,7 +154,7 @@ If you have shortcuts to pages inside of your project and you don't want them to
publishResources = false
{{< /multiconfig >}}
In this case, the file itself can be a branch bundle, leaf bundle or simple page (see exampleSite's `content/more/credits.en.md`). This causes its content to be contained in the sitemap.
The child page can be any type of content.
{{< multiconfig fm=true file="content/more/credits_index.en.md" >}}
title = "Credits"

3
exampleSite/content/configuration/sidebar/shortcutmenu/_index.pir.md
View file

@ -1,6 +1,7 @@
+++
description = "Add additional shortcut links to the sidebar"
title = "Shorrrtcut Menu"
options = ["disableShortcutsTitle"]
title = "Shortcut Menu"
weight = 5
+++
{{< piratify >}}

22
exampleSite/content/configuration/sidebar/width/_index.en.md
View file

@ -4,23 +4,23 @@ title = "Width"
weight = 1
+++
The theme reacts to browser resizes and adjusts the menu width accordingly.
The theme adjusts the menu width based on browser size.
If you dislike the default behavior, you can link to a CSS stylesheet or change it in your `layouts/partials/custom-header.html`.
If you want to change the chosen default width, you can add CSS variables to `layouts/partials/custom-header.html`.
## Change the Menu Width
## Changing Menu Width
The menu width adjusts automatically for different screen sizes for the following screen sizes:
The menu width changes for different screen sizes:
| Name | Screen Width | Menu Width |
| ---- | ------------- | ---------- |
| S | < 48rem | 14.375rem |
| M | 48rem - 60rem | 14.375rem |
| L | >= 60rem | 18.75rem |
| Screen Size | Screen Width | Menu Width |
| ----------- | ------------- | ---------- |
| Small | < 48rem | 14.375rem |
| Medium | 48rem - 60rem | 14.375rem |
| Large | >= 60rem | 18.75rem |
The values for the screen width breakpoints aren't configurable.
You can change the menu width but not the screen width breakpoints.
If you want to adjust the menu width you can define the following CSS variables. Note that `--MENU-WIDTH-S` applies to the menu flyout width in mobile mode for small screen sizes.
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>

2
exampleSite/content/configuration/siteorganization/_index.en.md → exampleSite/content/configuration/sitemanagement/_index.en.md
View file

@ -1,7 +1,7 @@
+++
alwaysopen = false
description = "Get yourself familiar with the general structure of your website"
title = "Site Organization"
title = "Site Management"
weight = 1
+++

2
exampleSite/content/configuration/siteorganization/_index.pir.md → exampleSite/content/configuration/sitemanagement/_index.pir.md
View file

@ -1,7 +1,7 @@
+++
alwaysopen = false
description = "Get yourself familiar with the general structure of your website"
title = "Site Organization"
title = "Site Management"
weight = 1
+++
{{< piratify >}}

62
exampleSite/content/configuration/sitemanagement/deployment/_index.en.md Normal file
View file

@ -0,0 +1,62 @@
+++
description = "Options for specific deployment needs"
options = ["disableExplicitIndexURLs"]
title = "Deployment Scenarios"
weight = 3
+++
## 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 >}}
> [!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
Exclusively use
{{< 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`.
## 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 >}}

1
exampleSite/content/configuration/siteorganization/deploymentscenarios/_index.pir.md → exampleSite/content/configuration/sitemanagement/deployment/_index.pir.md
View file

@ -1,5 +1,6 @@
+++
description = "Options for specific deployment needs"
options = ["disableExplicitIndexURLs"]
title = "Deployment Scenarios"
weight = 3
+++

97
exampleSite/content/configuration/sitemanagement/multilingual/_index.en.md Normal file
View file

@ -0,0 +1,97 @@
+++
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
- 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]
title = "My Website"
weight = 1
languageName = "English"
[languages.pir]
title = "Arrr, my Website"
weight = 2
languageName = "Pirrratish"
{{< /multiconfig >}}
2. Duplicate your content files and add language codes to their file names:
````plaintext
├── content
│ ├── basics
│ │ ├── first-content
| | | ├── _index.en.md
| | | └── _index.pir.md
│ │ ├── second-content
| | | ├── _index.en.md
| | | └── _index.pir.md
│ │ ├── third-content.en.md
│ │ └── third-content.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) 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 >}}

7
exampleSite/content/configuration/sitemanagement/multilingual/_index.pir.md Normal file
View file

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

33
exampleSite/content/configuration/sitemanagement/outputformats/_index.en.md Normal file
View file

@ -0,0 +1,33 @@
+++
description = "What other formats can a page be displayed in"
title = "Available Output Formats"
weight = 4
+++
## 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 >}}
This adds a printer icon in the topbar. 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 >}}

6
exampleSite/content/configuration/sitemanagement/outputformats/_index.pir.md Normal file
View file

@ -0,0 +1,6 @@
+++
description = "What other formats can a page be displayed in"
title = "Available Output Formats"
weight = 4
+++
{{< piratify >}}

37
exampleSite/content/configuration/sitemanagement/structure/_index.en.md Normal file
View file

@ -0,0 +1,37 @@
+++
description = "Your site's directory structure"
title = "Basic Structure"
weight = 1
+++
If you've followed the [Getting Started](introduction/quickstart) guide, your directory layout will look similar to this:
````plaintext
├── content
│ ├── basics
│ │ ├── first-content
| | | └── _index.md
│ │ ├── second-content
| | | └── _index.md
│ │ └── third-content.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/modifications/partials), to learn which files are allowed to be modified 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.

0
exampleSite/content/configuration/siteorganization/structure/_index.pir.md → exampleSite/content/configuration/sitemanagement/structure/_index.pir.md
View file

59
exampleSite/content/configuration/siteorganization/deploymentscenarios/_index.en.md
View file

@ -1,59 +0,0 @@
+++
description = "Options for specific deployment needs"
options = ["disableExplicitIndexURLs"]
title = "Deployment Scenarios"
weight = 3
+++
## Server Deployment
If you have no further requirements to your server deployment, you can skip the following page and choose of the broad range of available [options in a standard Hugo installation](https://gohugo.io/content-management/urls/).
If you have special requirements, the theme is capable of different scenarios, requiring the following mandatory settings in your `hugo.toml`. All settings not mentioned 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 >}}
### Private Web Server (LAN)
The same settings as with any of the public web server usage scenarios or
{{< multiconfig file=hugo >}}
baseURL = "/"
relativeURLs = true
{{< /multiconfig >}}
### File System
{{< multiconfig file=hugo >}}
baseURL = "/"
relativeURLs = true
{{< /multiconfig >}}
> [!WARNING]
> Using a `baseURL` with a subdirectory and `relativeURLs=true` are mutually exclusive due to the fact, that [Hugo does not apply the `baseURL` correctly](https://github.com/gohugoio/hugo/issues/12130).
>
> If you need both, you have to generate your site twice but with different settings into separate directories.
{{% notice note %}}
Sublemental pages (like `sitemap.xml`, `rss.xml`) and generated social media links inside of your pages will always be generated with absolute URLs and will not work if you set `relativeURLs=true`.
{{% /notice %}}
## URL Management
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} If you are using `uglyURLs=false` (Hugo's default), the theme will append an additional `index.html` to all page links to make your site be servable from the file system. If you don't care about the file system and only serve your page via a web server you can generate the links without this by setting `disableExplicitIndexURLs=true`.
{{< multiconfig file=hugo >}}
[params]
disableExplicitIndexURLs = true
{{< /multiconfig >}}

93
exampleSite/content/configuration/siteorganization/multilingual/_index.en.md
View file

@ -1,93 +0,0 @@
+++
description = "How to configure your site to be multilingual"
options = ["disableLanguageSwitchingButton"]
title = "Multilingual"
weight = 2
+++
The Relearn theme is compatible with [Hugo's multilingual mode](https://gohugo.io/content-management/multilingual/).
The theme supports a wide set of languages, also supporting languages written right to left.
{{% expand "Supported languages" %}}
- Arabic
- Simplified Chinese
- Traditional Chinese
- Czech
- Dutch
- English
- Finnish
- French
- German
- Hindi
- Hungarian
- Indonesian
- Italian
- Japanese
- Korean
- Polish
- Portuguese
- Romanian
- Russian
- Spanish
- Swahili
- Turkish
- Vietnamese
{{% /expand %}}
## Basic Configuration
This example will show you, how to convert your site created in the [Getting Started](introduction/quickstart) section to be multilingual using [translation by file name](https://gohugo.io/content-management/multilingual/#translation-by-file-name). You can also use [translation by content directory](https://gohugo.io/content-management/multilingual/#translation-by-content-directory), but this is out of the scope of this documentation.
Define your languages in your `hugo.toml` file. For example with English and Piratish English website.
{{< multiconfig file=hugo >}}
defaultContentLanguage = "en"
[languages]
[languages.en]
title = "My Website"
weight = 1
languageName = "English"
[languages.pir]
title = "Arrr, my Website"
weight = 2
languageName = "Pirrratish"
{{< /multiconfig >}}
Then, for each new page, append the _id_ of the language to the file.
````plaintext
├── content
│ ├── basics
│ │ ├── first-content
| | | ├── _index.en.md
| | | └── _index.pir.md
│ │ ├── second-content
| | | ├── _index.en.md
| | | └── _index.pir.md
│ │ ├── third-content.en.md
│ │ └── third-content.pir.md
│ ├── _index.en.md
│ └── _index.pir.md
├── themes
│ └── hugo-theme-relearn
│ └── ...
└── hugo.toml
````
## Configure Search
You may want to take a look into [search configuration](configuration/sidebar/search). It has some additional options for multilingual websites.
## Disable Language Switching
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Switching the language in the browser is a great feature, but for some reasons you may want to disable it.
Just set `disableLanguageSwitchingButton=true` in your `hugo.toml`
{{< multiconfig file=hugo >}}
[params]
disableLanguageSwitchingButton = true
{{< /multiconfig >}}

6
exampleSite/content/configuration/siteorganization/multilingual/_index.pir.md
View file

@ -1,6 +0,0 @@
+++
description = "How to configure your site to be multilingual"
title = "Multilingual"
weight = 2
+++
{{< piratify >}}

42
exampleSite/content/configuration/siteorganization/structure/_index.en.md
View file

@ -1,42 +0,0 @@
+++
description = "Your site's directory structure"
title = "Basic Structure"
weight = 1
+++
## Structure
If you've followed the [Getting Started](introduction/quickstart) guide, you are resulting in a directory layout similar to this
````plaintext
├── content
│ ├── basics
│ │ ├── first-content
| | | └── _index.md
│ │ ├── second-content
| | | └── _index.md
│ │ └── third-content.md
│ └── _index.md
├── themes
│ └── hugo-theme-relearn
│ └── ...
└── hugo.toml
````
Hugo creates a [union file system](https://gohugo.io/getting-started/directory-structure/#union-file-system), allowing you to mount two or more directories to the same location.
By default, it overlays your root directory on top of the directory of the Relearn theme. Files contained in your root directory will replace files in the Relearn theme's directory of the same location.
For example, the theme defines a file `themes/hugo-theme-relearn/layouts/partials/heading.html`, you can override it by defining your own file in `layouts/partials/heading.html`.
This makes it easy to customize the theme without having to edit files inside of the `themes` directory and so making it easier for you in the future to update the theme to a newer version.
> [!WARNING]
> If you are editing files inside the `themes/hugo-theme-relearn` directory, you're doing it wrong.
>
> See the [above paragraphs](#structure).
> [!WARNING]
> If you have cloned the theme repository and start editing files for your site in this clone, you're doing it wrong.
>
> Follow the [Getting Started](introduction/quickstart) guide.

10
exampleSite/content/content/frontmatter/_index.en.md
View file

@ -4,13 +4,13 @@ title = "Front Matter Reference"
weight = 6
+++
Each page in Hugo **has to define** front matter.
Every Hugo page must have front matter.
On top of [Hugo's front matter](https://gohugo.io/content-management/front-matter/#fields), you can use the additional theme settings listed below.
In addition to [Hugo's standard front matter](https://gohugo.io/content-management/front-matter/#fields), the Relearn theme offers extras settings listed here.
A front matter provided by the theme is marked with a {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} badge throughout the documentation.
Throughout the documentation, theme-specific front matter is marked with a {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} badge.
You set each theme front matter directly in the root of your page's front matter. For example, setting `math`
Add theme front matter directly to the root of your page's front matter. For example:
{{< multiconfig fm=true >}}
math = true
@ -22,7 +22,7 @@ You set each theme front matter directly in the root of your page's front matter
## All Front Matter
The example reflect example values. The defaults can be taken from the [annotated example](#annotated-front-matter) below or the individual documentation.
Here's a list of all available front matter with example values. Default values are described in the [annotated example](#annotated-front-matter) below or in each front matter's documentation.
{{< multiconfig fm=true >}}
{{% include "frontmatter.toml" %}}

79
exampleSite/content/content/imageeffects.en.md Normal file
View file

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

6
exampleSite/content/content/imageeffects.pir.md Normal file
View file

@ -0,0 +1,6 @@
+++
description = "How to extend image effects"
title = "Custom Image Effects"
weight = 3
+++
{{< piratify >}}

2
exampleSite/content/introduction/releasenotes/2/6.en.md
View file

@ -10,4 +10,4 @@ weight = -6
### New
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Your site can now be served from a subdirectory if you set `baseURL` in your `hugo.toml`. See the [documentation](configuration/siteorganization/deploymentscenarios) for a detailed example.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Your site can now be served from a subdirectory if you set `baseURL` in your `hugo.toml`. See the [documentation](configuration/sitemanagement/deployment) for a detailed example.

2
exampleSite/content/introduction/releasenotes/5/24.en.md
View file

@ -18,7 +18,7 @@ weight = -24
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The front matter option `menuTitle` is now deprecated in favor for Hugo's own `linkTitle`. You don't need to change anything as the old `menuTitle` option is still supported.
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The light themes have a bit more contrast for content text and headings. Also the syntaxhighlighting was changed to the more colorful MonokaiLight. This brings the syntaxhighlighting in sync with the corresponding dark theme variants, which are using Monokai. If you dislike this, you can create your own color variant file as [described here](configuration/appearance/branding#modify-shipped-variants).
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The light themes have a bit more contrast for content text and headings. Also the syntaxhighlighting was changed to the more colorful MonokaiLight. This brings the syntaxhighlighting in sync with the corresponding dark theme variants, which are using Monokai. If you dislike this, you can create your own color variant file as [described here](configuration/appearance/branding#modifying-variants).
### New

2
exampleSite/content/introduction/releasenotes/5/4.en.md
View file

@ -10,7 +10,7 @@ weight = -4
### Change
- {{% badge style="note" title=" " %}}Change{{% /badge %}} [With the proper settings](configuration/siteorganization/deploymentscenarios) in your `hugo.toml` your page is now servable from the local file system using `file://` URLs.
- {{% badge style="note" title=" " %}}Change{{% /badge %}} [With the proper settings](configuration/sitemanagement/deployment) in your `hugo.toml` your page is now servable from the local file system using `file://` URLs.
Please note that the searchbox will only work for this if you reconfigure your outputformat for the homepage in your `hugo.toml` from `json` to `search`. The now deprecated `json` outputformat still works as before, so there is no need to reconfigure your installation if it is only served from `http://` or `https://`.

24
exampleSite/content/introduction/releasenotes/7/0.en.md
View file

@ -19,11 +19,11 @@ weight = -0
- suffered from poor build performance for sites with 1000 or more pages
- reinvented the wheel instead of using available Hugo mechanisms
_What do I gain_, you may ask. A significant performance boost during build! Usually the build time has been cut at least in half for bigger sites. It is now possible to build even larger sites with 5000 or more pages. This was previously almost impossible due to rapidly increasing build time with the more pages you've introduced. For even bigger sites, the theme now has configurable performance optimizations (at the price of feature limitations).
_What do I gain_, you may ask. A significant performance boost during build! Usually, the build time has been cut at least in half for bigger sites. It is now possible to build even larger sites with 5000 or more pages. This was previously almost impossible due to rapidly increasing build time with the more pages you've introduced. For even bigger sites, the theme now has configurable performance optimizations (at the price of feature limitations).
If you haven't done customizations to any partials, you can update right away.
If you have customized your templates, in best cases you will get build warnings or even errors. In worst cases, your build succeeds but the site will not work as intended by you.
If you have customized your templates, in the best cases, you will get build warnings or even errors. In the worst cases, your build succeeds but the site will not work as intended by you.
Specifically, you will have to adapt your site if you have
@ -34,7 +34,7 @@ weight = -0
There is a separate section in the documentation covering these cases.
- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} This release changes the way, the search index and the dedicated search page are generated. This may require reconfiguration by you to still work as you have intended.
- {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} This release changes the way the search index and the dedicated search page are generated. This may require reconfiguration by you to still work as you have intended.
You need to remove the now obsolete `search` and `searchpage` output format from `[outputs.home]` in your `hugo.toml`, resulting in something similar to
@ -45,7 +45,7 @@ weight = -0
After that, your build will succeed but will most likely cause new defaults to be applied. With no further settings, in-page search, search popup and dedicated search page are all active by default. This can be reconfigured.
In addition you are now able to overwrite the default file name of the search index and the default page name of the dedicated search page by changing `searchIndexURL` and `searchPageURL` respectively in your `hugo.toml`.
In addition, you are now able to overwrite the default file name of the search index and the default page name of the dedicated search page by changing `searchIndexURL` and `searchPageURL` respectively in your `hugo.toml`.
See the [updated documentation](configuration/sidebar/search) for reference.
@ -53,13 +53,13 @@ weight = -0
- {{% badge style="note" title=" " %}}Change{{% /badge %}} Once again, the theme changed the font. We switched to the excellent [Roboto Flex](https://github.com/googlefonts/roboto-flex) font.
Care was taken, to configure the font to look similar to the previously used Work Sans. Nevertheless, in direct comparison you will see slight differences in appearance.
Care was taken to configure the font to look similar to the previously used Work Sans. Nevertheless, in direct comparison, you will see slight differences in appearance.
This change was necessary as the previously used font had display issues with [marked text](content/markdown#marked-text), contrast and some other minor stuff. As an aftermath, the number of requests and the download size were decreased when loading a page.
This change was necessary as the previously used font had display issues with [marked text](content/markdown#marked-text), contrast, and some other minor stuff. As an aftermath, the number of requests and the download size were decreased when loading a page.
Although the font was created by Google, it is licensed under OFL 1.1 and is delivered from your theme's installation. As always, no third party server calls involved.
Although the font was created by Google, it is licensed under OFL 1.1 and is delivered from your theme's installation. As always, no third-party server calls are involved.
If you have overridden the font to a [variable font](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide#variable_fonts_what_they_are_and_how_they_differ) in your installation either by hacking the CSS directly or by using any of the mechansims provided by the theme, you may have to adjust your CSS value for `font-variations-settings`. As it only applies to **variable fonts**, this should rarely be necessary.
If you have overridden the font to a [variable font](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide#variable_fonts_what_they_are_and_how_they_differ) in your installation either by hacking the CSS directly or by using any of the mechanisms provided by the theme, you may have to adjust your CSS value for `font-variations-settings`. As it only applies to **variable fonts**, this should rarely be necessary.
- {{% badge style="note" title=" " %}}Change{{% /badge %}} While switching the font, it was discovered that certain CSS variables were falsely named. You don't need to change anything in your custom variant stylesheet as the old names will be used as a fallback.
@ -67,19 +67,19 @@ weight = -0
- {{% badge style="note" title=" " %}}Change{{% /badge %}} The options and front matter to force loading a [math](shortcodes/math#force-loading-of-the-mathjax-library), [mermaid](shortcodes/mermaid#force-loading-of-the-mermaid-library) or [openapi](shortcodes/openapi#force-loading-of-the-swagger-ui-library) library has been changed.
Previously you had to set the unintuitive `disableMathJax=false` to force load the math library in case of a passthrough configuration. This is replaced by the simpler `math=true` or `math.force=true` and is now in line with [Hugo's official documentation](https://gohugo.io/content-management/mathematics/#step-1).
Previously, you had to set the unintuitive `disableMathJax=false` to force load the math library in case of a passthrough configuration. This is replaced by the simpler `math=true` or `math.force=true` and is now in line with [Hugo's official documentation](https://gohugo.io/content-management/mathematics/#step-1).
You don't need to change anything yet but will receive warnings if the old settings are used.
## New
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The docs received a much needed overhaul for all chapters.
- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The docs received a much-needed overhaul for all chapters.
Basically the structure was reorganized giving each topic its own page while keeping the amount of items for each menu level comprehensible by adding sub pages.
Basically, the structure was reorganized, giving each topic its own page while keeping the amount of items for each menu level comprehensible by adding sub-pages.
The docs now clearly differentiate between [configuration of your site](configuration), all things [writing page content](content) and the [shortcodes docs](shortcodes) that cover both topics, configuration and usage.
To give you a better overview what's possible with the theme, we introduced reference pages for all theme [configurations options](configuration/options) and [front matter](content/frontmatter) and mark each occurrence of such on all pages with badges {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} and {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}}.
To give you a better overview of what's possible with the theme, we introduced reference pages for all theme [configuration options](configuration/options) and [front matter](content/frontmatter) and mark each occurrence of such on all pages with badges {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} and {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}}.
Also, a lot of previously undocumented features are now included, namely

2
exampleSite/content/shortcodes/button.pir.md
View file

@ -1,5 +1,5 @@
+++
description = "Nice buttons on yer plank"
description = "Clickable buttons"
title = "Button"
+++
{{< piratify >}}

4
exampleSite/content/shortcodes/children/_index.en.md
View file

@ -1,5 +1,7 @@
+++
alwaysopen = false
frontmatter = ["ordersectionsby"]
options = ["ordersectionsby"]
description = "List the child pages of a page"
title = "Children"
+++
@ -39,7 +41,7 @@ The `children` shortcode lists the child pages of the current page and its desce
| **showhidden** | `false` | When `true`, child pages hidden from the menu will be displayed as well. |
| **description** | `false` | When `true` shows a short text under each page in the list. When no description or summary exists for the page, the first 70 words of the content is taken - [read more info about summaries on gohugo.io](https://gohugo.io/content/summaries/). |
| **depth** | `1` | The depth of descendants to display. For example, if the value is `2`, the shortcode will display two levels of child pages. To get all descendants, set this value to a high number eg. `999`. |
| **sort** | `auto` | The sort criteria of the displayed list.<br><br>- `auto` defaults to [`ordersectionsby` of the pages front matter](content/frontmatter)<br>&nbsp;&nbsp;&nbsp;&nbsp;or to [`ordersectionsby` of the site configuration](configuration/options)<br>&nbsp;&nbsp;&nbsp;&nbsp;or to `weight`<br>- `weight`<br>- `title`<br>- `linktitle`<br>- `modifieddate`<br>- `expirydate`<br>- `publishdate`<br>- `date`<br>- `length`<br>- `default` adhering to Hugo's default sort criteria|
| **sort** | `auto` | The sort criteria of the displayed list.<br><br>- `auto` defaults to `ordersectionsby` of the page's {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}}<br>&nbsp;&nbsp;&nbsp;&nbsp;or to `ordersectionsby` of the configuration {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}}<br>&nbsp;&nbsp;&nbsp;&nbsp;or to `weight`<br>- `weight`<br>- `title`<br>- `linktitle`<br>- `modifieddate`<br>- `expirydate`<br>- `publishdate`<br>- `date`<br>- `length`<br>- `default` adhering to Hugo's default sort criteria|
## Examples

2
exampleSite/content/shortcodes/expand.pir.md
View file

@ -1,5 +1,5 @@
+++
description = "Displays an expand'ble/collaps'ble sect'n o' text on yer plank"
description = "Expand'ble/collaps'ble sections of text"
title = "Expand"
+++
{{< piratify >}}

2
exampleSite/content/shortcodes/highlight.pir.md
View file

@ -1,5 +1,7 @@
+++
description = "Render code with a syntax highlighter"
frontmatter = ["highlightWrap"]
options = ["disableHoverBlockCopyToClipBoard", "disableInlineCopyToClipBoard", "highlightWrap"]
title = "Highlight"
+++
{{< piratify >}}

2
exampleSite/content/shortcodes/include/index.pir.md
View file

@ -1,5 +1,7 @@
+++
description = "Displays content from other Marrrkdown files"
frontmatter = ["include.errorlevel"]
options = ["include.errorlevel"]
title = "Include"
+++
{{< piratify >}}

2
exampleSite/content/shortcodes/math.pir.md
View file

@ -1,5 +1,7 @@
+++
description = "Beaut'fl math and chemical formulae"
frontmatter = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"]
options = ["customMathJaxURL", "math", "math.force", "mathJaxInitialize"]
title = "Math"
+++
{{< piratify >}}

4
exampleSite/content/shortcodes/mermaid.pir.md
View file

@ -1,5 +1,7 @@
+++
description = "Generrrat'n o' diagrrram an' flowcharrrt frrrom text 'n a similar manner as Marrrkdown"
description = "Generrrat'n o' diagrrram an' flowcharrrt frrrom text"
frontmatter = ["customMermaidURL", "mermaid.force", "mermaidInitialize", "mermaidZoom"]
options = ["customMermaidURL", "mermaid.force", "mermaidInitialize", "mermaidZoom"]
title = "Merrrmaid"
+++
{{< piratify true >}}

3
exampleSite/content/shortcodes/notice.pir.md
View file

@ -1,5 +1,6 @@
+++
description = "Disclaimerrrs t' help ye strrructurrre yer plank"
description = "Disclaimers to help you structure your page"
options = ["boxStyle"]
title = "Notice"
+++
{{< piratify >}}

4
exampleSite/content/shortcodes/openapi/_index.pir.md
View file

@ -1,6 +1,8 @@
+++
aliases = "/pir/shortcodes/swagger"
description = "Adds UI fer yer OpenAPI / Swaggerrr Specificat'ns"
description = "UI fer yer OpenAPI / Swaggerrr Specificat'ns"
frontmatter = ["customOpenapiURL", "openapi.errorlevel", "openapi.force"]
options = ["customOpenapiURL", "openapi.errorlevel", "openapi.force"]
title = "OpenAPI"
+++
{{< piratify >}}

2
exampleSite/content/shortcodes/siteparam.pir.md
View file

@ -1,5 +1,5 @@
+++
description = "Get value o' ship parrrams varrriables 'n yer plank"
description = "Get value o' ship parrrams"
title = "SiteParam"
+++
{{< piratify >}}

2
exampleSite/content/shortcodes/tabs.pir.md
View file

@ -1,5 +1,5 @@
+++
description = "Synchr'nize select'n o' content 'n different tabbed views"
description = "Show rrrambl'n 'n tabbed views"
title = "Tabs"
+++
{{< piratify >}}

2
layouts/partials/version.txt
View file

@ -1 +1 @@
6.4.0+5b09d87984bbe384a79f8a52e0442fd0bf2d4ade
6.4.0+39b403c10f701f48035c892325d4fb54e15a560f