• We’ll be using yml/yaml format for all examples down below, I recommend using yml over toml as it is easier to read.

  • You can find any YML to TOML converters if necessary.

Override theme template

By Hugo’s Lookup Order, you can override any part of a theme that you want. The following is a quick example.

Let’s say you wish the list was different. All you have to do is copy the list template:

your-site/themes/papermod/layouts/_defaults/list.html

And paste it under your own layouts folder:

your-site/layouts/_defaults/list.html

Then you’re free to make any changes you want to the list. When Hugo builds your site, your copy of list.html will be used instead of the theme’s list.html.

Enable Social-Metadata and SEO

These include OpenGraph, Twitter Cards and Schema.

1
2

params:
  env: production

or set HUGO_ENV as “production” in system env-vars

Failed to find a valid digest in the ‘integrity’ attribute for resource … ?

Read about How Subresource Integrity helps: Subresource_Integrity

Why was the asset not loading ? : How_browsers_handle_Subresource_Integrity

Solution:

Set the following in config.yml

1
2
3

params:
  assets:
    disableFingerprinting: true

Linked Issues:

Bundling Custom css with theme’s assets

  • For adding custom css to be bundled inside one minimized css

Create folder in yout project directory as

.(site root)
├── config.yml
├── content/
├── theme/hugo-PaperMod/
└── assets/
    └── css/
        └── extended/  <---
            ├── custom_css1.css <---
            └── any_name.css   <---

All css files inside assets/css/extended will be bundled !

Note: blank.css is just the placeholder so that it doesn’t break the theme when no files are present under assets/css/extended

Linked Issues:

Custom Head / Footer

Custom css/js can be added by way mentioned below.

.(site root)
├── config.yml
├── content/
├── theme/hugo-PaperMod/
└── layouts
    ├── partials
    │   ├── comments.html
    │   ├── extend_footer.html <---
    │   └── extend_head.html   <---
    └── robots.txt

Create a html page in directory structure as shown above.

Contents of extend_head.html will be added to head of page.

and contents of extend_footer.html will be added to bottom of page.

Add menu to site

You can add menu entries which will appear in the header of every page.

To do so, add a menu section to your site’s config.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

menu:
  main:
    - identifier: categories
      name: categories
      url: /categories/
      weight: 10
    - identifier: tags
      name: tags
      url: /tags/
      weight: 20
    - identifier: example
      name: example.org
      url: https://example.org
      weight: 30

name controls what will be displayed for the menu entry. url sets the URL that the entry points to. weight is used to control the positioning of entries.

For more information on menus, see the Hugo wiki page.

Pin a Post

Post can be pinned/ displayed top on the list by adding a weight=<num> var to page-variables

example:

1
2
3
4
5

---
title: "My Important post"
date: 2020-09-15T11:30:03+00:00
weight: 1
---

1
2
3
4
5

---
title: "My 2nd Important post"
date: 2020-09-15T11:30:03+00:00
weight: 2
---

Adding Custom Favicon(s)

We support the following paths under /static directory and can be added accordingly.

  • favicon.ico
  • favicon-16x16.png
  • favicon-32x32.png
  • apple-touch-icon.png
  • safari-pinned-tab.svg

  1. Favicon(s) can be generated by Favicon.io and can be simply put in /static folder.

  2. Other way is to add favicon(s) NOT located in /static folder.

    In site config add the following:

    1
2
3
4
5
6
7

    params:
  assets:
    favicon: "<link / absolute url>"
    favicon16x16: "<link / absolute url>"
    favicon32x32: "<link / absolute url>"
    apple_touch_icon: "<link / absolute url>"
    safari_pinned_tab: "<link / absolute url>"

    Note: absolute url means direct links to external resource: ex. https://web.site/someimage.png

1
2
3
4
5
6
7

params:
  assets:
    favicon: "/favicon.ico"
    favicon16x16: "/favicon-16x16.png"
    favicon32x32: "/favicon-32x32.png"
    apple_touch_icon: "/apple-touch-icon.png"
    safari_pinned_tab: "/safari-pinned-tab.svg"

Centering image in markdown

Add #center after image to center align an image

1

![name](path/to/image.png#center)

When using figure shortcode

use align=center to center image with captions

1

{{< figure align=center src="image.jpg" >}}

Using Hugo’s Syntax highlighter “chroma”

  1. Disable Highlight.js in site config.yml

    1
2
3

    params:
  assets:
    disableHLJS: true

  2. Set hugo’s markdown styling in site config.yml

    1
2
3
4
5
6
7
8

    markup:
  highlight:
    # anchorLineNos: true
    codeFences: true
    guessSyntax: true
    lineNos: true
    # noClasses: false
    style: monokai

  3. If you want lineNos: true, the background won’t be proper. This will only work with noClasses: false or pygmentsUseClasses: true. Read Generate Syntax Highlighter CSS

    Add the following to assets/css/extended/custom.css

    1
2
3

    .chroma {
  background-color: unset;
}

    More Info : Configure Markup - Highlight

Search not working ?

If you are using a CDN to server assets from a different domain, search would break

Why? Take a look at fastsearch.js#L35.

We fetch the index.json (where the search function looks for the keywords typed) one level up of the website search.min.js is hosted on.

We have used this insted of assigning baseURL so as to work with multilingual websites ex. example.com/fr/ and websites being placed under a subdirectory ex. example.com/blog/.

To fix for single language websites hosting assets from CDN, this you may override fastsearch.js#L35 and placing appropriate URL as in

1

xhr.open("GET", "https://example.com/index.json");

References