Skip to main content
GOHUGO
Head

Head

This is a GoHugo theme component that solves the old question “What tags belong into the <head> tag of my website?” Set it up, configure it, forget it’s there. This component adds a multitude of tags and is extensively configurable.

If you want to learn about all that is possible in the <head> tag then have a look at htmlhead.dev — or just trust this module to do “all the right things”.

Add this module 
[[module.imports]]
path = "github.com/davidsneighbour/hugo-head"
disable = false
ignoreConfig = false
ignoreImports = false
Latest Version
v1.1.29 (2023-07-03)

General setup

1<head>
2 {{ partial "head.html" . }}
3</head>

Set up hugo-head by adding it to your head tag and remove all other tags from your head – they are included in hugo-head. Then configure the module, setup all other features and forget about it.

hugo-head uses opiniated defaults that can be overridden via configuration.

1[dnb]
2  [dnb.head]
3    charset = 'utf-8'
4    nobase = false
5    viewport = 'width=device-width, initial-scale=1'

1dnb:
2  head:
3    charset: utf-8
4    nobase: false
5    viewport: width=device-width, initial-scale=1

1{
2   "dnb": {
3      "head": {
4         "charset": "utf-8",
5         "nobase": false,
6         "viewport": "width=device-width, initial-scale=1"
7      }
8   }
9}
  • charset: Sets the global charset for the page. Do not set or change this if you have no reason for it. UTF8 is the proper way to encode your content. If your content (language, encoding) is located in a multibyte region this might change to UTF16 or UTF32.
  • nobase: Use the websites BaseURL as base tag. This means all relative links will be based on this URL. Depending on your way of writing markup this might be useful to fix local links and references. If you keep this setting out of your configuration then the base-tag will be set to your BaseURL setting. Set it to true and no base tag will be used, all references on any page will be based on that pages URL.
  • viewport: This is a tag that defines how to display the website on various devices and with what setup. If you don’t know about this, then keep it out of your config and the best default setting will be used.

title and description generation

The title will be generated from the title frontmatter of the content file. If we are on the home page the site title is used. On subsequent list-pages a (Page n) is added. On all pages except the homepage a separator and the sites title is added at the end.

1[dnb]
2  [dnb.head]
3    separator = ' | '

1dnb:
2  head:
3    separator: ' | '

1{
2   "dnb": {
3      "head": {
4         "separator": " | "
5      }
6   }
7}

The title generation is able to add a “(page n)” to the title on list pages if you save your pagination dictionary in a scratch called paginator. The following would be a sample of how to accomplish that:

1{{- $paginator := dict -}}
2{{- if eq "home" .Kind -}}
3 {{- $paginator = $.Paginate (where site.RegularPages "Type" "in" site.Params.mainSections) -}}
4{{- else if .IsNode -}}
5 {{- $paginator = $.Paginator -}}
6{{- end -}}
7{{- .Scratch.Set "paginator" $paginator -}}

It is also possible to add an additional sectiontitle between page and site title. This is set via sectiontitle frontmatter. Either add that value individually per page or via cascade in the section’s _index.md.

The description is generated from the description frontmatter of the content file. If no description is configured then site.Params.description is used.

Speed optimisation

To be written.

Author generation

hugo-head can transform the following configuration parameters into header tags that add author information (Note: this is for compatibility reasons directly under the author section in the configuration, NOT the dnb.head section):

1[author]
2  email = 'email'
3  homepage = 'website'
4  name = 'name'

1author:
2  email: email
3  homepage: website
4  name: name

1{
2   "author": {
3      "email": "email",
4      "homepage": "website",
5      "name": "name"
6   }
7}

If you are using hugo-humans or hugo-publisher then hugo-head will integrate these header tags in addition to these modules features automatically for you after you configure the module.

Stylesheets

hugo-head adds a simple stylesheet pipeline to your website. It expects an entry point in assets/scss/style.scss or any other configured file in assets.

1[dnb]
2  [dnb.head]
3    [dnb.head.styles]
4      entrypoint = 'scss/theme.scss'

1dnb:
2  head:
3    styles:
4      entrypoint: scss/theme.scss

1{
2   "dnb": {
3      "head": {
4         "styles": {
5            "entrypoint": "scss/theme.scss"
6         }
7      }
8   }
9}

Configuration for GoHugo’s SASS/SCSS processing can be piped through via the configuration. The available options for the compilation of SCSS can be found in GoHugo’s documentation.

1[dnb]
2  [dnb.head]
3    [dnb.head.styles]
4      method = 'postcss'
5      [dnb.head.styles.options]
6        enableSourceMap = true
7        includePaths = ['node_modules/']
8        outputStyle = 'compressed'
9        targetPath = 'assets/theme.css'

 1dnb:
 2  head:
 3    styles:
 4      method: postcss
 5      options:
 6        enableSourceMap: true
 7        includePaths:
 8        - node_modules/
 9        outputStyle: compressed
10        targetPath: assets/theme.css

 1{
 2   "dnb": {
 3      "head": {
 4         "styles": {
 5            "method": "postcss",
 6            "options": {
 7               "enableSourceMap": true,
 8               "includePaths": [
 9                  "node_modules/"
10               ],
11               "outputStyle": "compressed",
12               "targetPath": "assets/theme.css"
13            }
14         }
15      }
16   }
17}

Translations

If the current page has a translation then it will be linked in your header. This feature does not require additional configuration.

SEO

To be written.

Series

If the current page has a page following or coming before then hugo-head will automatically create .PrevInSection/.NextInSection links for the head. This feature does not require additional configuration.

Social Graph

If you are using hugo-social then hugo-head will integrate these header tags in additon to these modules features automatically for you after you configure the module.

If you are using hugo-opensearch then hugo-head will integrate these header tags in additon to these modules features automatically for you after you configure the module.

PWA

If you are using hugo-pwa then hugo-head will integrate these header tags in additon to these modules features automatically for you after you configure the module. Note, that it does NOT script inclusion in the site footer, so these tags still need to be added in your footer layouts.

Humans.txt

If you are using hugo-humans then hugo-head will integrate these header tags in additon to these modules features automatically for you after you configure the module.

Alternates

hugo-head prints all configured alternate links for a page. If you find alternates for output types you do not wish to include, then you have configured your output format wrong. Have a look at the documentation of notAlternative and how to enable/disable output formats.

Verification

hugo-head can add verification-meta-tag to your header for any of the following services. Just add the value of the meta-tag (NOT the full meta-tag) to your configuration.

1[dnb]
2  [dnb.head]
3    [dnb.head.verification]
4      alexa = ''
5      bing = ''
6      google = ''
7      norton = ''
8      pinterest = ''
9      yandex = ''

1dnb:
2  head:
3    verification:
4      alexa: ""
5      bing: ""
6      google: ""
7      norton: ""
8      pinterest: ""
9      yandex: ""

 1{
 2   "dnb": {
 3      "head": {
 4         "verification": {
 5            "alexa": "",
 6            "bing": "",
 7            "google": "",
 8            "norton": "",
 9            "pinterest": "",
10            "yandex": ""
11         }
12      }
13   }
14}

Note: You should prefer to verify your ownership via a file in your site root or via DNS record to minimise the output on your pages. The less headers you have the better.

Others

hugo-head can add various obscure and weird other tags to your headers if you configure them. Think about the usefulness of these tags though, less is more.

 1[params]
 2  [params.dnb]
 3    [params.dnb.head]
 4      [params.dnb.head.verification]
 5        disable = ['referrer', 'phone_transcription']
 6        latitude = ''
 7        longitude = ''
 8        monetization = ''
 9        notranslate = false
10        placename = ''
11        region = ''

 1params:
 2  dnb:
 3    head:
 4      verification:
 5        disable:
 6        - referrer
 7        - phone_transcription
 8        latitude: ""
 9        longitude: ""
10        monetization: ""
11        notranslate: false
12        placename: ""
13        region: ""

 1{
 2   "params": {
 3      "dnb": {
 4         "head": {
 5            "verification": {
 6               "disable": [
 7                  "referrer",
 8                  "phone_transcription"
 9               ],
10               "latitude": "",
11               "longitude": "",
12               "monetization": "",
13               "notranslate": false,
14               "placename": "",
15               "region": ""
16            }
17         }
18      }
19   }
20}

Hooks

hugo-head implements template hooks via hugo-hooks and provides the following hooks:

Hook Description
head-init hooks in after the opening head tag. Do not open this to output anything. Just to initialise any of your plugins.
head-start hooks in after the initial first tags that belong at the beginning of your head section.
head-post-speed-optimisation
head-post-description
head-post-author
head-pre-css hooks in before the stylesheets are printed.
head-post-css hooks in after the stylesheets are printed.
head-post-translations
head-post-seo
head-post-series
head-post-social
head-post-opensearch
head-post-pwa
head-post-humans
head-post-alternates
head-post-verification
head-end hooks in at the end of the head right before the closing tag.

Sites and Projects using hugo-head

Published: Fri, Jun 30, 2023 at 5:31pm (Last Modified: Tue, Aug 22, 2023 at 8:13pm)
Tags:
Share: LinkedIn Facebook Twitter