Width

The theme adjusts the menu width based on browser size.

If you want to change the chosen default width, you can add CSS variables to layouts/partials/custom-header.html.

Changing Menu Width

The menu width changes for different screen sizes:

You can change the menu width but not the screen width breakpoints.

To adjust the menu width, use these CSS variables. Note that --MENU-WIDTH-S is for the mobile menu flyout on small screens.

<style>
:root {
    --MENU-WIDTH-S: 14.375rem;
    --MENU-WIDTH-M: 14.375rem;
    --MENU-WIDTH-L: 18.75rem;
}
</style>

Header & Footer

Title

Option With the default partials for the logo, The site title will also be used for the text at the top of the sidebar. If you want to show a different text in the sidebar, you can overwrite linkTitle.

[params]
  linkTitle = 'Relearn'

params:
  linkTitle: Relearn

{
   "params": {
      "linkTitle": "Relearn"
   }
}

Home Button Configuration

By default, the theme displays a home button between search form and navigation menu. The Home button serves as an alternative to clicking the logo.

Option To hide the Home button on the left menu, set disableLandingPageButton=true.

[params]
  disableLandingPageButton = true

params:
  disableLandingPageButton: true

{
   "params": {
      "disableLandingPageButton": true
   }
}

Option To change its icon or text, configure the landingPageName for your defined languages.

[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'

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

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

If this option isn’t set for a specific language, it will use these default values

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

params:
  landingPageName: <i class="fa-fw fas fa-home"></i> Home

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

History

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

[params]
  showVisitedLinks = true

params:
  showVisitedLinks: true

{
   "params": {
      "showVisitedLinks": true
   }
}

Footer

To change the menu footer, edit the layouts/partials/menu-footer.html file. Check out the Partials section for more ways to customize your site.

Search

Configure Search

The theme offers three levels of search through the menu’s search form:

1. In-page search: Highlights search terms on the current page
2. Search popup: Opens a popup with results from other pages
3. Dedicated search page: Accessible by clicking the magnifier glass or pressing ENTER

Each level requires the previous one to be enabled. If no search is configured, the search form won’t appear.

Option 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

[params]
  disableSearch = true
  disableSearchIndex = true
  disableSearchPage = true

params:
  disableSearch: true
  disableSearchIndex: true
  disableSearchPage: true

{
   "params": {
      "disableSearch": true,
      "disableSearchIndex": true,
      "disableSearchPage": true
   }
}

Option 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

[params]
  searchIndexURL = 'omnisearchindex.js'
  searchPageURL = 'omnisearch'

params:
  searchIndexURL: omnisearchindex.js
  searchPageURL: omnisearch

{
   "params": {
      "searchIndexURL": "omnisearchindex.js",
      "searchPageURL": "omnisearch"
   }
}

Supported Languages

The Lunr 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

Mixed Language Support

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

[params]
  additionalContentLanguage = ['en']

params:
  additionalContentLanguage:
  - en

{
   "params": {
      "additionalContentLanguage": [
         "en"
      ]
   }
}

You can add multiple languages to this array.

Menus

The theme can build menu trees from the structure of your page files or from Hugo’s build in menu feature.

• Option All configuration options in your hugo.toml apply to all menus but can be changed individually.

• Front Matter In case of page structure menus, individual configuration is done via a page’s front matter.

• Menu. In case of Hugo menus, individual configuration is done via a menu entry’s configuration.

Expand State of Submenus

Option Front Matter You can change how submenus appear with alwaysopen.

Menu For Hugo menus, you have to set params.alwaysopen instead.

If alwaysopen=false for any given entry, its children will not be shown in the menu as long as it is not necessary for the sake of navigation.

The theme generates the expand state based on the following rules:

• all parent entries of the active page including their visible siblings are shown regardless of any settings
• immediate child entries of the active entry are shown regardless of any settings
• if not overridden, all other first level entries behave like they would have been given alwaysopen=false
• if not overridden, all other entries of levels besides the first behave like they would have been given alwaysopen=true
• all visible entries show their immediate child entries if alwaysopen=true; this proceeds recursively
• all remaining entries are not shown

alwaysopen = false

alwaysopen: false

{
   "alwaysopen": false
}

Expander for Submenus

Option Front Matter Set collapsibleMenu=true to show submenus as collapsible trees with a clickable expander.

Menu For Hugo menus, you have to set params.collapsibleMenu=true instead.

collapsibleMenu = true

collapsibleMenu: true

{
   "collapsibleMenu": true
}

Ordering Menu Entries

By Weight

Front Matter Menu Hugo provides a simple way to handle order of your entries by setting the weight front matter to a number.

Hugo menus can only be sorted using the weight method.

weight = 5

weight: 5

{
   "weight": 5
}

By Other

Using the weight for sorting can get cumbersome if you, for example, just want to sort alphabetically. Each time you add a new page in the set of pages, you may have to renumber some or all of them to make space for the new page.

Option Front Matter Use ordersectionsby to sort by other aspects. See the children shortcode for a complete list.

ordersectionsby = 'linktitle'

ordersectionsby: linktitle

{
   "ordersectionsby": "linktitle"
}

Title for Menu Entries

Front Matter A page’s linkTitle or title front matter will be used for naming a menu entry of a page menu, in that order if both are defined. Using linkTitle helps to shorten the text for menu entries if the page’s title is too descriptive.

Menu A menu entry’s title or name will be used for naming a menu entry of a Hugo menu, in that order if both are defined.

For example for a page named install/linux.md

+++
linkTitle = 'Linux'
title = 'Install on Linux'
+++

---
linkTitle: Linux
title: Install on Linux
---

{
   "linkTitle": "Linux",
   "title": "Install on Linux"
}

Icons for Menu Entries

Front Matter For page menus, add a menuPre to insert any HTML code before the menu label. You can also set menuPost to insert HTML code after the menu label.

Menu For Hugo menus, add a pre to insert any HTML code before the menu label. You can also set post to insert HTML code after the menu label.

If pageRef is set for the menu entry and no pre or post was configured, menuPre and menuPost of the referenced page will be taken.

The example below uses the GitHub icon for an entry of a page menu.

+++
menuPre = '<i class="fab fa-github"></i> '
title = 'GitHub Repo'
+++

---
menuPre: '<i class="fab fa-github"></i> '
title: GitHub Repo
---

{
   "menuPre": "\u003ci class=\"fab fa-github\"\u003e\u003c/i\u003e ",
   "title": "GitHub Repo"
}

Disable Menu Entries

You may want to structure your entries in a hierarchical way but don’t want to generate clickable parent entries? The theme got you covered.

For Page Menus

To stay with the initial example: Suppose you want first-chapter/first-page appear in the sidebar but don’t want to generate a page for it. So the entry in the sidebar should not be clickable but should be expandable.

For this, open content/first-chapter/first-page/_index.md and add the following front matter

+++
[_build]
  render = 'never'
+++

---
_build:
  render: never
---

{
   "_build": {
      "render": "never"
   }
}

For Hugo Menus

Just don’t give your parent menu entry configuration a url or pageRef. See the next section for a special case.

If you want to learn how to configure different Hugo menus for each language, see the official docs.

+++
[menu]
  [[menu.addendum]]
    name = 'Parent 1'
    weight = 1

  [[menu.addendum]]
    name = 'Child 1'
    parent = 'Parent 1'
    url = 'https://example.com/1'

  [[menu.addendum]]
    name = 'Parent 2'
    weight = 2

  [[menu.addendum]]
    name = 'Child 2'
    parent = 'Parent 2'
    url = 'https://example.com/2'
+++

---
menu:
  addendum:
  - name: Parent 1
    weight: 1
  - name: Child 1
    parent: Parent 1
    url: https://example.com/1
  - name: Parent 2
    weight: 2
  - name: Child 2
    parent: Parent 2
    url: https://example.com/2
---

{
   "menu": {
      "addendum": [
         {
            "name": "Parent 1",
            "weight": 1
         },
         {
            "name": "Child 1",
            "parent": "Parent 1",
            "url": "https://example.com/1"
         },
         {
            "name": "Parent 2",
            "weight": 2
         },
         {
            "name": "Child 2",
            "parent": "Parent 2",
            "url": "https://example.com/2"
         }
      ]
   }
}

Title for Menus

Each menu may have an optional title above its tree. This must be activated for each menu by setting disableMenuTitle=false for each sidebar menu configuration.

Front Matter For page menus, set the menuTitle front matter for the root page of the menu. For example in the home page for the default sidebar menu. If no menuTitle was set, the title will be taken from your translation files by the key <identifier>-menuTitle, where <identifier> is the identifier of your sidebar menu configuration.

Menu For Hugo menus, the title will be taken from your translation files by the key <identifier>-menuTitle, where <identifier> is the identifier of your sidebar menu configuration.

If you don’t want to fiddle around with your translation files, you also have the possibility to let the title be taken from the menu definition. For that, define a nested menu that only has one top-level entry without url or pageRef.

In this case, the title or name is taken for the menu heading.

If you want to learn how to configure different Hugo menus for each language, see the official docs.

+++
[menu]
  [[menu.addendum]]
    name = 'A Menu Title for the Whole Menu'

  [[menu.addendum]]
    name = 'A Menu Entry Title for Child 1'
    parent = 'Parent'
    url = 'https://example.com/1'
    weight = 1

  [[menu.addendum]]
    name = 'A Menu Entry Title for Child 2'
    parent = 'Parent'
    url = 'https://example.com/2'
    weight = 2
+++

---
menu:
  addendum:
  - name: A Menu Title for the Whole Menu
  - name: A Menu Entry Title for Child 1
    parent: Parent
    url: https://example.com/1
    weight: 1
  - name: A Menu Entry Title for Child 2
    parent: Parent
    url: https://example.com/2
    weight: 2
---

{
   "menu": {
      "addendum": [
         {
            "name": "A Menu Title for the Whole Menu"
         },
         {
            "name": "A Menu Entry Title for Child 1",
            "parent": "Parent",
            "url": "https://example.com/1",
            "weight": 1
         },
         {
            "name": "A Menu Entry Title for Child 2",
            "parent": "Parent",
            "url": "https://example.com/2",
            "weight": 2
         }
      ]
   }
}

Title for the Predefined Shortcut Menu

Option By default, the predefined shortcut menu has a the title More (in the English translation).

You can disable this title with disableShortcutsTitle=true.

[params]
  disableShortcutsTitle = true

params:
  disableShortcutsTitle: true

{
   "params": {
      "disableShortcutsTitle": true
   }
}

To change the title, override your translation file.

[shortcuts-menuTitle]
other = "Other Great Stuff"

Defining Sidebar Menus

Option Front Matter Menus are defined using the sidebarmenus option.

You can define as many menus, as you like. If you don’t overwrite this option, the theme defaults to

[[sidebarmenus]]
  disableTitle = true
  identifier = 'home'
  main = true
  pageRef = ''
  type = 'page'

[[sidebarmenus]]
  disableTitle = false
  identifier = 'shortcuts'
  main = false
  type = 'menu'

sidebarmenus:
- disableTitle: true
  identifier: home
  main: true
  pageRef: ""
  type: page
- disableTitle: false
  identifier: shortcuts
  main: false
  type: menu

{
   "sidebarmenus": [
      {
         "disableTitle": true,
         "identifier": "home",
         "main": true,
         "pageRef": "",
         "type": "page"
      },
      {
         "disableTitle": false,
         "identifier": "shortcuts",
         "main": false,
         "type": "menu"
      }
   ]
}

Parameter

Redefining Sidebar Menus for Certain Pages

Suppose you are building a site that contains a topmost blog and documentation section.

When the user is on one of the blog pages he should only see a menu containing all blog pages, while on a documentation page he should only see a menu containing all doc pages.

Directory structure:

content
├── blog
│   ├── post-1.md
│   ├── post-2.md
│   ├── post-3.md
│   └── _index_.md
├── docs
│   ├── topic-1.md
│   ├── topic-2.md
│   ├── topic-3.md
│   └── _index_.md
└── _index.md

Option Front Matter Using Hugo’s cascade feature, we can redefine the menus once in blog/_index.md and docs/_index.md setting sidebarmenus so they will be used in all children pages.

+++
title = 'Blog'

[[cascade]]
  [cascade.params]
    [[cascade.params.sidebarmenus]]
      identifier = 'blog'
      pageRef = '/blog'
      type = 'page'
+++

---
cascade:
- params:
    sidebarmenus:
    - identifier: blog
      pageRef: /blog
      type: page
title: Blog
---

{
   "cascade": [
      {
         "params": {
            "sidebarmenus": [
               {
                  "identifier": "blog",
                  "pageRef": "/blog",
                  "type": "page"
               }
            ]
         }
      }
   ],
   "title": "Blog"
}

+++
title = 'Documentation'

[[cascade]]
  [cascade.params]
    [[cascade.params.sidebarmenus]]
      identifier = 'docs'
      pageRef = '/docs'
      type = 'page'
+++

---
cascade:
- params:
    sidebarmenus:
    - identifier: docs
      pageRef: /docs
      type: page
title: Documentation
---

{
   "cascade": [
      {
         "params": {
            "sidebarmenus": [
               {
                  "identifier": "docs",
                  "pageRef": "/docs",
                  "type": "page"
               }
            ]
         }
      }
   ],
   "title": "Documentation"
}

Displaying Arbitrary Links in a Page Menu

You may have the need to add arbitrary links at some point in your menu that are initially not backed by a page. These are called crosslinks.

Assume the following structure

content
├── reference
│   ├── ref-a.md
│   ├── ref-b.md
│   ├── ref-c.md
│   └── _index_.md
├── topic-blue.md
├── topic-red.md
├── topic-yellow.md
└── _index_.md

You now want to include ref-b as separate entry after topic-green in your menu.

For that create a new page with the following front matter

+++
menuPageRef = '/reference/ref-b'
title = 'Topic Green'
+++

---
menuPageRef: /reference/ref-b
title: Topic Green
---

{
   "menuPageRef": "/reference/ref-b",
   "title": "Topic Green"
}

Front Matter If you want to link to an external page instead, you can use menuUrl instead of menuPageRef.

Pages defining a crosslink are never part of the arrow navigation and are skipped instead.

So with the above example and alphabetical sorting of the menu entries, pressing on topic-blue will skip the newly added topic-green and instead will load topic-red.

Having sub pages below a page that defines a crosslink is undefined.

Displaying Pages Exclusively in a Hugo Menu

Sometimes you want to hide pages from the page menu but instead want to show them in a Hugo menu. For that you have two choices

1. Create a headless branch bundle, _index.md in its own folder with the below front matter. The branch bundle will not be contained in the sitemap.

   content/showcase/_index.en.md

   toml yaml json

   +++
   title = 'Showcase'
   
   [_build]
     list = 'never'
     publishResources = true
     render = 'always'
   +++

   ---
   _build:
     list: never
     publishResources: true
     render: always
   title: Showcase
   ---

   {
      "_build": {
         "list": "never",
         "publishResources": true,
         "render": "always"
      },
      "title": "Showcase"
   }

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.

   content/more/_index.en.md

   toml yaml json

   +++
   [_build]
     list = 'never'
     publishResources = false
     render = 'never'
   +++

   ---
   _build:
     list: never
     publishResources: false
     render: never
   ---

   {
      "_build": {
         "list": "never",
         "publishResources": false,
         "render": "never"
      }
   }

   The child page can be any type of content.

   content/more/credits_index.en.md

   toml yaml json

   +++
   title = 'Credits'
   +++

   ---
   title: Credits
   ---

   {
      "title": "Credits"
   }