Partials

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.

Extending Scripts

A common question is how to add extra CSS styles or JavaScript to your site. This depends on what you need.

Adding JavaScript or Stylesheets to All Pages

To add JavaScript files or CSS stylesheets to every page, you can include them in layouts/partials/custom-header.html or layouts/partials/custom-footer.html.

However, this can make your site larger than necessary if these files are only needed on a few pages. The next section explains how to add dependencies only when needed.

Custom Shortcodes with Dependencies

Some shortcodes need extra JavaScript and CSS files. The theme only loads these when the shortcode is used. You can use this for your own shortcodes too.

For example, to create a shortcode called myshortcode that needs the jquery library:

1. Create the shortcode file layouts/shortcodes/myshortcode.html and add the folloging line somewhere:

   ​

   layouts/shortcodes/myshortcode.html

   ...
   {{- .Page.Store.Set "hasMyShortcode" true }}
   ...

2. Option Add this to your hugo.toml:

   hugo.

   toml yaml json

   [params]
     [params.relearn]
       [params.relearn.dependencies]
         [params.relearn.dependencies.myshortcode]
           name = 'MyShortcode'

   params:
     relearn:
       dependencies:
         myshortcode:
           name: MyShortcode

   {
      "params": {
         "relearn": {
            "dependencies": {
               "myshortcode": {
                  "name": "MyShortcode"
               }
            }
         }
      }
   }

3. Create loader file layouts/partials/dependencies/myshortcode.html:

   ​

   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.

{{- partial "dependencies.gotmpl" (dict "page" . "location" "mylocation") }}

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.

Image Effects

This page shows you, how to configure custom image effects on top of existing ones.

This setting can also be overridden by your front matter.

If you don’t configure anything in your hugo.toml, the image effects default to

Default Values

[imageEffects]
  border = false
  lazy = true
  lightbox = true
  shadow = false

imageEffects:
  border: false
  lazy: true
  lightbox: true
  shadow: false

{
   "imageEffects": {
      "border": false,
      "lazy": true,
      "lightbox": true,
      "shadow": false
   }
}

Configuration

Option You can change these settings in your hugo.toml and add arbitrary custom effects as boolean values (like bg-white in the below snippet).

[params]
  [params.imageEffects]
    bg-white = true
    border = true
    lazy = false

params:
  imageEffects:
    bg-white: true
    border: true
    lazy: false

{
   "params": {
      "imageEffects": {
         "bg-white": true,
         "border": true,
         "lazy": false
      }
   }
}

This would result in

[imageEffects]
  bg-white = true
  border = true
  lazy = false
  lightbox = true
  shadow = false

imageEffects:
  bg-white: true
  border: true
  lazy: false
  lightbox: true
  shadow: false

{
   "imageEffects": {
      "bg-white": true,
      "border": true,
      "lazy": false,
      "lightbox": true,
      "shadow": false
   }
}

Example

With this configuration in effect, the following URL

![Minion](https://octodex.github.com/images/minion.png)

would result in

<img src="https://octodex.github.com/images/minion.png" loading="lazy" alt="Minion" class="bg-white border nolazy lightbox noshadow">

Styling Effects

If the resulting effect value is

• true: add a class with the effect’s name
• false: add a class with the effect’s name and a “no” prefix

Styles for default effects are contained in the theme. Add styles for your custom effects to layouts/partials/content-header.html.

For the above example you could add styles for both boolean cases:

<style>
img.bg-white {
  background-color: white;
}
img.nobg-white {
  background-color: transparent;
}
</style>

Topbar

The theme comes with a reasonably configured topbar. You can learn how to configure the defaults in this section.

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.

Areas

The default configuration comes with three predefined areas that may contain an arbitrary set of buttons.

• start: shown between menu and breadcrumb
• end: shown on the opposite breadcrumb side in comparison to the start area
• more: shown when pressing the 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):

• sidebar: opens the sidebar flyout if in mobile layout
• toc: opens the table of contents in an overlay
• edit: browses to the editable page if the editURL parameter is set
• print: browses to the chapter’s printable page if print support was activated
• prev: browses to the previous page if there is one
• next: browses to the [next page]authoring/frontmatter/topbar(#arrow-navigation) if there is one
• more: 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 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.

{{ partial "topbar/button/more.html" (dict
  "page" .
  "onempty" "disable"
)}}

Defining Own Buttons

Button Types

The theme distinguishes between two types of buttons:

• 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: the template for the 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).

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) as well as the more button (see 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).

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) or with an overlay containing arbitrary content like the toc button (layouts/partials/topbar/button/toc.html).

For displaying an area in the button’s overlay, see Area-Button.

Parameter

Area-Button

Contains the basic functionality to display area overlay buttons (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).

Parameter

Predefined Buttons

The predefined buttons by the theme (all other buttons besides the more and toc button in layouts/partials/topbar/button).

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.

Parameter

Predefined Overlay-Buttons

The predefined buttons by the theme that open an overlay (the more and toc button in layouts/partials/topbar/button).

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.

Parameter

Page Designs

A page is displayed by exactly one page design. The Relearn theme offers the page designs home, chapter, and default.

A page design usually consists of

• an archetype file: a template for creating new Markdown files with this design
• content view files: represented by Hugo’s reserved type front matter and backed by matching partials
• CSS styles

If no type is set in your front matter, the page is treated as if type='default' was set.

All shipped designs use the theme’s framework from themes/hugo-theme-learn/layouts/_default/baseof.html, containing of the same topbar and sidebar but can change how content appears in the center of the page.

Using a Page Design

Regardless of shipped or custom page design, you are using them in the same way.

Creating a Page Designs

To make a custom page design:

1. Choose a name (for example, mydesign)

2. Create a content view file at layouts/mydesign/views/article.html

   ​

   layouts/mydesign/views/article.html

   <article class="mydesign">
     <header class="headline">
   {{ partial "content-header.html" . }}
     </header>
   <div class="article-subheading">AWESOME</div>
   {{ partial "heading-pre.html" . }}{{ partial "heading.html" . }}{{ partial "heading-post.html" . }}
   {{ partial "article-content.html" . }}
     <footer class="footline">
   {{ partial "content-footer.html" . }}
     </footer>
   </article>

   In this file, you can customize the page design as needed. Typically, you’ll want to:

   • Set a class at the article element for custom CSS styles
   • Use {{ partial "article-content.html" . }} to show your page content

3. Create an archetype file at archetypes/mydesign.md (optional)

   ​

   archetypes/mydesign.md

   +++
   title = "{{ replace .Name "-" " " | title }}"
   type = "mydesign"
   +++
   
   This is my new design.

4. Add CSS in file layouts/partials/custom-header.html (optional)

   ​

   layouts/partials/custom-header.html

   <style>
   .mydesign .article-subheading {
     font-size: 72rem;
   }
   .mydesign a {
     background-color: pink;
   }
   </style>

Partials

The above example uses layouts/mydesign/views/article.html but you have some others

• layouts/mydesign/baseof.html: Completely redefine the whole HTML structure, none of the other listed partials will be used
• layouts/mydesign/views/menu.html: Defines the sidebar menu layout
• layouts/mydesign/views/body.html: Determines what to contain in the content area (for example a single page, a list of pages, a tree of sub pages)
• layouts/mydesign/views/article.html: Controls how one page’s content and title are displayed

Output Formats

In addition to the output formats coming with the theme, you can create your own output formats.

Starting from Scratch

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:

1. Create a file layouts/_default/baseof.myformat.html
2. Implement all the necessary code in this file

Using the Theme’s Structure

If you want to keep the general framework and only change specific parts, you can override these files:

• 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 a real-world example, check out the print output format implementations

• layouts/_default/views/body.print.html
• layouts/_default/views/menu.print.html
• layouts/_default/views/storeOutputFormat.print.html

Taxonomies

This page explains how to show custom taxonomies on your pages.

For more details, check the official docs on setting up custom taxonomies and using them in your content.

Default Behavior

The Relearn theme automatically shows Hugo’s 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.

[taxonomies]
  category = 'categories'
  mycustomtag = 'mycustomtags'
  tag = 'tags'

taxonomies:
  category: categories
  mycustomtag: mycustomtags
  tag: tags

{
   "taxonomies": {
      "category": "categories",
      "mycustomtag": "mycustomtags",
      "tag": "tags"
   }
}

Showing Custom Taxonomies

To display your custom taxonomy terms, add this to your page (usually in layouts/partials/content-footer.html):

{{ partial "term-list.html" (dict
  "page" .
  "taxonomy" "mycustomtags"
  "icon" "layer-group"
) }}

Parameter