noiruh/hurion.eu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
nhurion
2025-02-19 00:16:57 +01:00
parent 1d9cd91fcd
commit d89698593b
1293 changed files with 55933 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
themes/hugo-theme-relearn/docs/content/configuration/customization/_index.en.md Normal file
View File

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

8
themes/hugo-theme-relearn/docs/content/configuration/customization/_index.pir.md Normal file
View File

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

148
themes/hugo-theme-relearn/docs/content/configuration/customization/designs/index.en.md Normal file
View File

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

7
themes/hugo-theme-relearn/docs/content/configuration/customization/designs/index.pir.md Normal file
View File

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

73
themes/hugo-theme-relearn/docs/content/configuration/customization/extending/_index.en.md Normal file
View File

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

8
themes/hugo-theme-relearn/docs/content/configuration/customization/extending/_index.pir.md Normal file
View File

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

80
themes/hugo-theme-relearn/docs/content/configuration/customization/imageeffects.en.md Normal file
View File

@@ -0,0 +1,80 @@
+++
categories = ["explanation", "howto"]
description = "How to extend image effects"
options = ["imageEffects"]
title = "Image Effects"
weight = 4
+++
This page shows you, how to configure custom [image effects](authoring/markdown#image-effects) on top of existing ones.
This setting can also [be overridden by your front matter](authoring/imageeffects).
If you don't configure anything in your `hugo.toml`, the image effects default to
## Default Values
{{< multiconfig >}}
[imageEffects]
border = false
dataurl = false
inlinecontent = false
lazy = true
lightbox = true
shadow = false
{{< /multiconfig >}}
## Configuration
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can change these settings in your `hugo.toml` and add arbitrary custom effects as boolean values (like `bg-white` in the below snippet).
{{< multiconfig file=hugo >}}
[params]
[params.imageEffects]
bg-white = true
border = true
lazy = false
{{< /multiconfig >}}
This would result in
{{< multiconfig >}}
[imageEffects]
bg-white = true
border = true
dataurl = false
inlinecontent = false
lazy = false
lightbox = true
shadow = false
{{< /multiconfig >}}
### Example
With this configuration in effect, the following URL
````markdown {title="Markdown"}
![Minion](https://octodex.github.com/images/minion.png)
````
would result in
````html {title="HTML"}
<img src="https://octodex.github.com/images/minion.png" loading="lazy" alt="Minion" class="bg-white border lightbox">
````
## Styling Effects
If the resulting effect value is `true` a class with the effect's name will be added.
Styles for default effects are contained in the theme. Add styles for your custom effects to `layouts/partials/content-header.html`.
For the above custom effect you could add the following style:
````html {title="layouts/partials/content-header.html"}
<style>
img.bg-white {
background-color: white;
}
</style>
````

8
themes/hugo-theme-relearn/docs/content/configuration/customization/imageeffects.pir.md Normal file
View File

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

71
themes/hugo-theme-relearn/docs/content/configuration/customization/linkeffects.en.md Normal file
View File

@@ -0,0 +1,71 @@
+++
categories = ["explanation", "howto"]
description = "How to extend link effects"
options = ["linkEffects"]
title = "Link Effects"
weight = 3
+++
This page shows you, how to configure custom [link effects](authoring/markdown#link-effects) on top of existing ones.
This setting can also [be overridden by your front matter](authoring/linkeffects).
If you don't configure anything in your `hugo.toml`, the link effects default to
## Default Values
{{< multiconfig >}}
[linkEffects]
download = false
target = false
{{< /multiconfig >}}
## Configuration
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can change these settings in your `hugo.toml` and add arbitrary custom effects as boolean values (like `bg-white` in the below snippet).
{{< multiconfig file=hugo >}}
[params]
[params.linkEffects]
bg-white = true
target = '_blank'
{{< /multiconfig >}}
This would result in
{{< multiconfig >}}
[linkEffects]
bg-white = true
download = false
target = '_blank'
{{< /multiconfig >}}
### Example
With this configuration in effect, the following URL
````markdown {title="Markdown"}
[Magic in new window](images/magic.gif)
````
would result in
````html {title="HTML"}
<a href="/images/magic.gif?target=_blank" target="_blank" class="bg-white">Magic in new window</a>
````
## Styling Effects
If the resulting effect value is `true` a class with the effect's name will be added.
Styles for default effects are contained in the theme. Add styles for your custom effects to `layouts/partials/content-header.html`.
For the above custom effect you could add the following style:
````html {title="layouts/partials/content-header.html"}
<style>
a.bg-white {
background-color: white;
}
</style>
````

8
themes/hugo-theme-relearn/docs/content/configuration/customization/linkeffects.pir.md Normal file
View File

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

229
themes/hugo-theme-relearn/docs/content/configuration/customization/outputformats/_index.en.md Normal file
View File

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

7
themes/hugo-theme-relearn/docs/content/configuration/customization/outputformats/_index.pir.md Normal file
View File

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

46
themes/hugo-theme-relearn/docs/content/configuration/customization/partials/index.en.md Normal file
View File

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

7
themes/hugo-theme-relearn/docs/content/configuration/customization/partials/index.pir.md Normal file
View File

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

54
themes/hugo-theme-relearn/docs/content/configuration/customization/taxonomy.en.md Normal file
View File

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

8
themes/hugo-theme-relearn/docs/content/configuration/customization/taxonomy.pir.md Normal file
View File

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

182
themes/hugo-theme-relearn/docs/content/configuration/customization/topbar/_index.en.md Normal file
View File

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

9
themes/hugo-theme-relearn/docs/content/configuration/customization/topbar/_index.pir.md Normal file
View File

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

BIN
themes/hugo-theme-relearn/docs/content/configuration/customization/topbar/topbar-areas.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
themes/hugo-theme-relearn/docs/content/configuration/customization/topbar/topbar-closed.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.7 KiB