Configuration

Configuration

Hugo reads its configuration from hugo.yaml in the root of your Hugo site. The config file is where you can configure all aspects of your site. Check out the config file for this site exampleSite/hugo.yaml on GitHub to get a comprehensive idea of available settings and best practices.

Navigation

Menu

Top right menu is defined under the menu.main section in the config file:

hugo.yaml
menu:
  main:
    - name: Documentation
      pageRef: /docs
      weight: 1
    - name: Blog
      pageRef: /blog
      weight: 2
    - name: About
      pageRef: /about
      weight: 3
    - name: Search
      weight: 4
      params:
        type: search
    - name: GitHub
      weight: 5
      url: "https://github.com/imfing/hextra"
      params:
        icon: github

There are different types of menu items:

  1. Link to a page in the site with pageRef
    - name: Documentation
      pageRef: /docs
  2. Link to an external URL with url
    - name: GitHub
      url: "https://github.com"
  3. Search bar with type: search
    - name: Search
      params:
        type: search
  4. Icon
    - name: GitHub
      params:
        icon: github

These menu items can be sorted by setting the weight parameter.

Logo and Title

To modify the default logo, edit hugo.yaml and add the path to your logo file under static directory. Optionally, you can change the link that users are redirected to when clicking on your logo, as well as set the width & height of the logo in pixels.

hugo.yaml
params:
  navbar:
    displayTitle: true
    displayLogo: true
    logo:
      path: images/logo.svg
      dark: images/logo-dark.svg
      link: /
      width: 40
      height: 20

Sidebar

Main Sidebar

For the main sidebar, it is automatically generated from the structure of the content directory. See the Organize Files page for more details.

To exclude a single page from the left sidebar, set the sidebar.exclude parameter in the front matter of the page:

content/docs/guide/configuration.md
---
title: Configuration
sidebar:
  exclude: true
---

Extra Links

Sidebar extra links are defined under the menu.sidebar section in the config file:

hugo.yaml
menu:
  sidebar:
    - name: More
      params:
        type: separator
      weight: 1
    - name: "About"
      pageRef: "/about"
      weight: 2
    - name: "Hugo Docs ↗"
      url: "https://gohugo.io/documentation/"
      weight: 3

Right Sidebar

Table of Contents

Table of contents is automatically generated from the headings in the content file. It can be disabled by setting toc: false in the front matter of the page.

content/docs/guide/configuration.md
---
title: Configuration
toc: false
---

Page Edit Link

To configure the page edit link, we can set the params.editURL.base parameter in the config file:

hugo.yaml
params:
  editURL:
    enable: true
    base: "https://github.com/your-username/your-repo/edit/main"

The edit links will be automatically generated for each page based on the provided url as root directory. If you want to set edit link for a specific page, you can set the editURL parameter in the front matter of the page:

content/docs/guide/configuration.md
---
title: Configuration
editURL: "https://example.com/edit/this/page"
---

Footer

Copyright

To modify the copyright text displayed in your website’s footer, you’ll need to create a file named i18n/en.yaml. In this file, specify your new copyright text as shown below:

i18n/en.yaml
copyright: "© 2024 YOUR TEXT HERE"

For your reference, an example i18n/en.yaml file can be found in the GitHub repository. Additionally, you could use Markdown format in the copyright text.

Others

Favicon

To customize the favicon for your site, place icon files under the static folder to override the default favicons from the theme:

    • android-chrome-192x192.png
    • android-chrome-512x512.png
    • apple-touch-icon.png
    • favicon-16x16.png
    • favicon-32x32.png
    • favicon-dark.svg
    • favicon.ico
    • favicon.svg
    • site.webmanifest
  • Include favicon.ico, favicon.svg and favicon-dark.svg files in your project to ensure your site’s favicons display correctly.

    While favicon.ico is generally for older browsers, favicon.svg and favicon-dark.svg are supported by modern browsers. Use tools like favicon.io or favycon to generate such icons.

    Theme Configuration

    Use the theme setting to configure the default theme mode and toggle button, allowing visitors to switch between light or dark mode.

    hugo.yaml
    params:
      theme:
        # light | dark | system
        default: system
        displayToggle: true

    Options for theme.default:

    • light - always use light mode
    • dark - always use dark mode
    • system - sync with the operating system setting (default)

    The theme.displayToggle parameter allows you to display a toggle button for changing themes. When set to true, visitors can switch between light or dark mode, overriding the default setting.

    Page Width

    The width of the page can be customized by the params.page.width parameter in the config file:

    hugo.yaml
    params:
      page:
        # full (100%), wide (90rem), normal (1280px)
        width: wide

    There are three available options: full, wide, and normal. By default, the page width is set to normal.

    Similarly, the width of the navbar and footer can be customized by the params.navbar.width and params.footer.width parameters.

    Search Index

    Full-text search powered by FlexSearch is enabled by default. To customize the search index, set the params.search.flexsearch.index parameter in the config file:

    hugo.yaml
    params:
      # Search
      search:
        enable: true
        type: flexsearch
    
        flexsearch:
          # index page by: content | summary | heading | title
          index: content

    Options for flexsearch.index:

    • content - full content of the page (default)
    • summary - summary of the page, see Hugo Content Summaries for more details
    • heading - level 1 and level 2 headings
    • title - only include the page title

    To customize the search tokenize, set the params.search.flexsearch.tokenize parameter in the config file:

    hugo.yaml
    params:
        # ...
        flexsearch:
          # full | forward | reverse | strict 
          tokenize: forward

    Options for flexsearch.tokenize:

    • strict - index whole words
    • forward - incrementally index words in forward direction
    • reverse - incrementally index words in both directions
    • full - index every possible combination

    To exclude a page from the search index, set the excludeSearch: true in the front matter of the page:

    content/docs/guide/configuration.md
    ---
    title: Configuration
    excludeSearch: true
    ---

    Google Analytics

    To enable Google Analytics, set services.googleAnalytics.ID flag in hugo.yaml:

    hugo.yaml
    services:
      googleAnalytics:
        ID: G-MEASUREMENT_ID
    Last updated on