Customization

Usage scenarios

The theme is usable in different scenarios, requiring the following mandatory settings in your hugo.toml. All settings not mentioned can be set to your liking.

Public Webserver from Root

baseURL = 'https://example.com/'

baseURL: https://example.com/

{
   "baseURL": "https://example.com/"
}

Public Webserver from Subdirectory

baseURL = 'https://example.com/mysite/'
relativeURLs = false

baseURL: https://example.com/mysite/
relativeURLs: false

{
   "baseURL": "https://example.com/mysite/",
   "relativeURLs": false
}

Private Webserver (LAN)

The same settings as with any of the public webserver usage scenarios or

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

{
   "baseURL": "/",
   "relativeURLs": true
}

File System

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

{
   "baseURL": "/",
   "relativeURLs": true
}

[params]
  disableExplicitIndexURLs = true

params:
  disableExplicitIndexURLs: true

{
   "params": {
      "disableExplicitIndexURLs": true
   }
}

Activate search

If not already present, add the following lines in your hugo.toml file.

[outputs]
  home = ['html', 'rss', 'search']

outputs:
  home:
  - html
  - rss
  - search

{
   "outputs": {
      "home": [
         "html",
         "rss",
         "search"
      ]
   }
}

This will generate a search index file at the root of your public folder ready to be consumed by the Lunr search library. Note that the search outputformat was named json in previous releases but was implemented differently. Although json still works, it is now deprecated.

Activate dedicated search page

You can add a dedicated search page for your page by adding the searchpage outputformat to your home page by adding the following lines in your hugo.toml file. This will cause Hugo to generate a new file http://example.com/mysite/search.html.

[outputs]
  home = ['html', 'rss', 'search', 'searchpage']

outputs:
  home:
  - html
  - rss
  - search
  - searchpage

{
   "outputs": {
      "home": [
         "html",
         "rss",
         "search",
         "searchpage"
      ]
   }
}

You can access this page by either clicking on the magnifier glass or by typing some search term and pressing ENTER inside of the menu’s search box .

Activate 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 as seen below:

[outputs]
  home = ['html', 'rss', 'print', 'search']
  page = ['html', 'rss', 'print']
  section = ['html', 'rss', 'print']

outputs:
  home:
  - html
  - rss
  - print
  - search
  page:
  - html
  - rss
  - print
  section:
  - html
  - rss
  - print

{
   "outputs": {
      "home": [
         "html",
         "rss",
         "print",
         "search"
      ],
      "page": [
         "html",
         "rss",
         "print"
      ],
      "section": [
         "html",
         "rss",
         "print"
      ]
   }
}

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.

Home Button Configuration

If the disableLandingPageButton option is set to false, a Home button will appear on the left menu. It is an alternative for clicking on the logo. To edit the appearance, you will have to configure the landingPageName for the defined languages:

[languages]
  [languages.en]
    [languages.en.params]
      landingPageName = "<i class='fas fa-home'></i> Home"

  [languages.pir]
    [languages.pir.params]
      landingPageName = "<i class='fas fa-home'></i> Arrr! Homme"

languages:
  en:
    params:
      landingPageName: <i class='fas fa-home'></i> Home
  pir:
    params:
      landingPageName: <i class='fas fa-home'></i> Arrr! Homme

{
   "languages": {
      "en": {
         "params": {
            "landingPageName": "\u003ci class='fas fa-home'\u003e\u003c/i\u003e Home"
         }
      },
      "pir": {
         "params": {
            "landingPageName": "\u003ci class='fas fa-home'\u003e\u003c/i\u003e Arrr! Homme"
         }
      }
   }
}

If this option is not configured for a specific language, they will get their default values:

landingPageName = "<i class='fas fa-home'></i> Home"

landingPageName: <i class='fas fa-home'></i> Home

{
   "landingPageName": "\u003ci class='fas fa-home'\u003e\u003c/i\u003e Home"
}

The home button is going to look like this:

Social Media Meta Tags

You can add social media meta tags for the Open Graph protocol and Twitter Cards to your site. These are configured as mentioned in the Hugo docs.

Change the Menu Width

The menu width adjusts automatically for different screen sizes.

The values for the screen width breakpoints aren’t configurable.

If you want to adjust the menu width you can define the following CSS variables in your custom-header.html. Note that --MENU-WIDTH-S applies to the menu flyout width in mobile mode for small screen sizes.

:root {
    --MENU-WIDTH-S: 14.375rem;
    --MENU-WIDTH-M: 14.375rem;
    --MENU-WIDTH-L: 18.75rem;
}

Change the Main Area’s Max 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 line are usually harder to read.

If you are unhappy with the default, you can define the following CSS variable in your custom-header.html and set the value to your liking. If you want to use all available space, select a really big value like 1000rem;

:root {
    --MAIN-WIDTH-MAX: 80.25rem;
}

Own Shortcodes with JavaScript Dependencies

Certain shortcodes make use of additional JavaScript files. The theme only loads these dependencies if the shortcode is used. To do so correctly the theme adds management code in various files.

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

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

2. Add the following snippet to your hugo.toml

   hugo.

   toml yaml json

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

   params:
     relearn:
       dependencies:
         myshortcode:
           location: footer
           name: MyShortcode

   {
      "params": {
         "relearn": {
            "dependencies": {
               "myshortcode": {
                  "location": "footer",
                  "name": "MyShortcode"
               }
            }
         }
      }
   }

3. Add the dependency loader file layouts/partials/dependencies/myshortcode.html. The loader file will be appended to your header or footer, dependend on the location setting in your hugo.toml.

   <script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>

Character casing is relevant!

• 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 params.relearn.dependencies in your hugo.toml must match the base file name of your loader file.

See the math, mermaid and openapi shortcodes for examples.

Output Formats

Certain parts of the theme can be changed for support of your own output formats. Eg. if you define a new output format PLAINTEXT in your hugo.toml, you can add a file layouts/partials/header.plaintext.html to change the way, the page header should look like for that output format.

React to Variant Switches in JavaScript

Once a color variant is fully loaded, either initially or by switching the color variant manually with the variant selector, the custom event themeVariantLoaded on the document will be dispatched. You can add an event listener and react to changes.

document.addEventListener( 'themeVariantLoaded', function( e ){
  console.log( e.detail.variant ); // `relearn-light`
});

Partials

The Relearn theme has been built to be as configurable as possible by defining multiple partials

In themes/hugo-theme-relearn/layouts/partials/, you will find all the partials defined for this theme. If you need to overwrite something, don’t change the code directly. Instead follow this page. You’d create a new partial in the layouts/partials folder of your local project. This partial will have the priority.

This theme defines the following partials :

• header.html: the header of the page. See output-formats
• footer.html: the footer of the page. See output-formats
• body.html: the body of the page. The body may contain of one or many articles. See output-formats
• article.html: the output for a single article, can contain elements around your content. See output-formats
• menu.html: left menu. Not meant to be overwritten
• search.html: search box. Not meant to be overwritten
• custom-header.html: custom headers in page. Meant to be overwritten when adding CSS imports. Don’t forget to include style HTML tag directive in your file.
• custom-footer.html: custom footer in page. Meant to be overwritten when adding JavaScript. Don’t forget to include javascript HTML tag directive in your file.
• favicon.html: the favicon
• heading.html: side-wide configuration to change the pages title headings.
• heading-pre.html: side-wide configuration to prepend to pages title headings. If you override this, it is your responsibility to take the page’s headingPre setting into account.
• heading-post.html: side-wide configuration to append to pages title headings. If you override this, it is your responsibility to take the page’s headingPost setting into account.
• logo.html: the logo, on top left hand corner
• meta.html: HTML meta tags, if you want to change default behavior
• menu-pre.html: side-wide configuration to prepend to menu items. If you override this, it is your responsibility to take the page’s menuPre setting into account.
• menu-post.html: side-wide configuration to append to menu items. If you override this, it is your responsibility to take the page’s menuPost setting into account.
• menu-footer.html: footer of the the left menu
• toc.html: table of contents
• content.html: the content page itself. This can be overridden if you want to display page’s meta data above or below the content.
• content-header.html: header above the title, has a default implementation but you can overwrite it if you don’t like it.
• content-footer.html: footer below the content, has a default implementation but you can overwrite it if you don’t like it.