Hugo Site Customization

Getting started? Hugo Blox has a collection of beautiful templates for you to choose from.

Want to personalize the template? No problem, a Hugo Blox template is fully customizable. In fact, you can change so many elements, it would be difficult to find the original template it was made from.

This page explains some common site customizations. You might also be interested in customizing the homepage.

Check out the Guides for details on each feature and for more advanced customization by extending.

Personalise your URL

Give your site a professional appearance, such as your-name.com, whilst preventing it getting locked into one specific host such as GitHub Pages (your-name.github.io) or Netlify (your-name.netlify.app).

View the Custom Domain guide →

Website icon

Are you looking to customize the desktop and mobile icon (aka favicon) which appears in your site’s Progressive Web App (PWA) and web browser tab?

Save your icon as a square 512x512 pixel image named icon.png and place the image in your root assets/media/ folder, creating the folders if they don’t already exist.

Web browsers can cache icons, so you may not notice an immediate change unless the browser cache is cleared.

Appearance

The following options in config/_default/params.yaml can be set to personalise the appearance of your site:

appearance:
  mode: light
  color: blue

Light and Dark Modes

Choose the default appearance of your site with the mode option. Options include light, dark, or system.

When choosing the system option, the appearance will automatically match the appearance of the user’s device.

Want to let visitors override the default appearance? Show a theme toggle button in the site header - check out the Header section below.

Color Themes

Choose the color scheme of your site with the color option

Options include blue, cyan, green, indigo, purple, red, rose, sky, teal, and zinc.

Alternatively, create your own color scheme:

1. Download an existing color scheme
2. Edit the colors
3. Rename the file to match your new color scheme, for example river.css
4. Move the file to your assets/css/themes/ folder, creating the folders if they don’t already exist
5. Use your new color scheme by setting color: river (or whatever you named your file) in config/_default/params.yaml

Fonts

Use your own fonts, such as from Google Fonts, by adding them via Custom CSS (see Extend Hugo Blox).

Header

You can choose from the following options to customise the site header containing the navigation bar:

header:
  navbar:
    # Display the navigation bar?
    enable: true
    # Choose a built-in navigation blox or create your own
    blox: "navbar"
    # Align menu links: `left`, `center`, or `right`
    align: "center"
    # Fix the navigation bar to the top of the page
    fixed_to_top: true
    logo:
      # Logo text
      text: ""
      # Logo filename in `assets/media/` folder
      filename: "logo.svg"
    # Shop a call-to-action button in the top right?
    button:
      enable: true
      text: "Get Started"
      url: "https://hugoblox.com/templates/"
    # Let the user choose between light or dark mode?
    show_theme_chooser: true
    # Let the user search from the navigation bar?
    show_search: true
    # Attempt to automatically highlight the active menu link? Can be disabled for complex sites.
    highlight_active_link: true
    # Show a language chooser (if you have translated your site content)?
    show_translations: true
    # If `show_translations` is enabled, do you wish to hide the current language name?
    hide_language_name: false

Want to swap out the navbar header blox for a different layout?

You can do that too by choosing a blox from the blox repository or from your local layouts/partials/components/headers/ folder.

Menu items

The main menu links in the navigation bar can be edited in the config/_default/menu.yaml file.

For example, to link to the homepage and an about page, we paste their relative URLs from the root of the site:

main:
  - name: Home
    url: /
    weight: 10
  - name: About
    url: about/
    weight: 20

To order your links, set the weight options to any ascending numeric values. Here we use multiples of ten so that it’s easier to change the order in the future if we have many menu items.

Linking to page sections

To link to a section of the homepage, use the form #ID where ID corresponds to the section id field. For example, #posts references a section with id: posts. You can rename your IDs in _index.md, just remember to use a dash (-) instead of spaces in the ID.

Sub-Menus

To create a dropdown sub-menu, add identifier: a-unique-reference to the parent item and parent: a-unique-reference to the child item, replacing a-unique-reference with a unique reference of your choice.

Example of creating a Tags sub-menu:

main:
  - name: Home
    url: /
    weight: 10
  - name: Tags
    identifier: tags
    weight: 20
  - name: Academic
    parent: tags
    url: tags/academic/
    weight: 10

Learn more about the underlying Hugo menu system here.

Footer

Add your own message to the footer of a site using the notice text field in config/_default/params.yaml. The notice field supports two dynamic variables: {year} displays the current year and {license} will link to the copyright license if one is enabled.

Optionally, you can choose a Creative Commons copyright license too:

footer:
  block: minimal
  copyright:
    notice: '© {year} Me. This work is licensed under {license}'
    license:
      enable: true
      allow_derivatives: false
      share_alike: true
      allow_commercial: false
  # For multilingual sites, show a language chooser in the footer?
  show_translations: true

A copyright_license can also be displayed on a per-page basis by adding the option directly to a page’s front matter (see Page Features page).

For multilingual sites, you can display a language chooser in the footer using show_translations.

Want to swap out the minimal footer block for a different layout?

You can do that too by choosing a block from the block repository or from your local layouts/partials/components/footers/ folder.

Hide Published With Hugo Blox Builder

Want to hide or customize the Published with Hugo Blox Builder notice in the footer?

The notice can be automatically removed whilst ❤️ sponsoring ❤️ with All Access.

Otherwise, please leave the attribution to this open source initiative that you benefit from intact.

The notice can be translated. If the notice is not already translated for your language, refer to the Language guide to translate it.

Localization

The date, time, and address formats can be localized in config/_default/params.yaml. For example,

locale:
  date_format: 'Jan 2, 2006'
  time_format: '3:04 PM'
  address_format: en-us

Date/time options

Hugo uses the following constants to format dates and times:

To modify the format, edit date_format and time_format in config/_default/params.yaml using the above constants. For example, some common formats are:

Address formats

If you display addresses on your site, such as for events or contact sections, you can choose an address format.

Don’t see the format you want? Contribute one or override the linked file to add your own.

Interface language

Personalise the interface text or choose a translation

Site Features

Refer to the Guides section of the documentation site for the main features such as SEO, page sharing, and commenting.

Additional site features that can be customized in params.yaml are covered below.

SEO

View the SEO guide →

Commenting

View the Commenting guide →

Analytics

View the Analytics guide →

Social sharing

View the Social Sharing guide →

Code syntax highlighting

Hugo’s code syntax highlighter is named Chroma.

Chroma’s light or dark styles are automatically applied to your code blocks in light mode and dark mode, respectively.

The syntax highlighting styles can be customized using the Custom CSS feature (see Extend Hugo Blox).

Latex math

features:
  math: true

Diagrams

Draw diagrams on pages using the Markdown-like Mermaid syntax.

Diagrams are automatically detected and rendered without the need to configure anything.

Privacy

View the Privacy guide →

Link to edit page

Let your users suggest improvements to pages.

Simply update the URL and branch to match those of your GitHub repository. Then set editable: true to page front matter and a link will be added to the page footer to let users edit the page within the GitHub Editor.

features:
  repository:
    url: 'https://github.com/<username>/<repository>'
    content_dir: content
    branch: main

Get feedback

Add a feedback widget to your docs pages (Book layout) to get feedback on your content and prioritise which pages to improve.

The feedback widget is displayed when Google Analytics is setup on a live, production Hugo site. You can simulate a live site locally by changing Hugo’s environment to production: hugo server -e production. It can be disabled by setting feedback: false in the front matter.

Here’s how you can configure your feedback responses in params.yaml:

features:
  feedback:
    responses:
      positive: 'Glad to hear it! [Any ideas for improvements?](https://github.com/<USERNAME>/<REPO>/issues/new)'
      negative: 'Sorry to hear that. [Please tell us how we can improve](https://github.com/<USERNAME>/<REPO>/issues/new).'

Note: browsers which block Google Analytics may also block the feedback widget.

Recommendations

Recommend similar content to your readers at the end of pages.

In your page front matter:

show_related: true

Search

View the Search guide →

Security

View the Security guide →

Maps

Choose a map provider in order to display a map in the Contact block.

The following map providers are supported: '' (no map), google, mapnik, or mapbox. Some map providers provide an api_key to set.

For example, to use Mapnik’s map service:

features:
  map:
    provider: 'mapnik'
    api_key: ''
    zoom: 15

After choosing a provider, set your map coordinates in your Contact widget in order to display a map:

content:
  coordinates:
    latitude: '37.4275'
    longitude: '-122.1697'

If you do not know your coordinates, you can retrieve them from Google Maps after searching for a location, or from alternative apps.