Hugo DFD Metadata Module README

DFD Hugo module for metadata for .Page

Basic documentation for metadata-mod-hugo-dfd, a Hugo module by Daniel F. Dickinson for handling page metadata intended to be used in generating the ‘head’ section, as well as used in page elements.

Status

build-and-verify

Demo site

https://metadata-mod.wildtechgarden.ca/

GitHub repository

https://github.com/danielfdickinson/metadata-mod-hugo-dfd

Features

Basic usage

Importing the module

  1. The first step to making use of this module is to add it to your site or theme. In your configuration file:

    config.toml

    [module]
        [[module.imports]]
            path = "github.com/danielfdickinson/metadata-mod-hugo-dfd"
    

    OR config.yaml

    module:
      imports:
        - path: github.com/danielfdickinson/metadata-mod-hugo-dfd
    
  2. Execute

    hugo mod get github.com/danielfdickinson/metadata-mod-hugo-dfd
    hugo mod tidy
    

Summary of configurable params

Unless otherwise noted, params may be per-page (in frontmatter), or in the site ‘params’ section in you site configuration file(s). Page params override site-wide params.

Param Default Description
datesPreserveTimezone false If true in page or site params, then the timezone of the date is not adjusted. If this is not the case, all dates are converted to UTC. You can of course use .Local or other date functions to adjust the output of the resulting date.
description (nil) If present acts as the the description metadata (see Features above). Note 17
emptyElementStyle (nil) If emptyElementStyle is set to self-close in params (site or per-page), then empty tags produced by this module use ‘self-closing’ form, otherwise ‘void style’ Note 6 Note 9
internalTemplatesOverrideRobotsTXT true Site-level params only. When true overrides the internal template for robots.txt (robots.txt) with one from this module Note 8
internalTemplatesOverrideRSS true Site-level params only. When true overrides the internal template for RSS feeds (rss.xml) with one from this module
internalTemplatesOverrideSitemap true Site-level params only. When true overrides the internal template for Sitemap protocol file (sitemap.xml) with one from this module
metadataNumSeeAlso 10 Number of related pages to return as the see-also metadata
microformatsEnable true If true pull in the facebook, opengraph, schema, and twitter_cards microformats into <head> Note 11
microformatsOpenGraphEnable true If true add the opengraph.html microformat to <head> Note 13
microformatsSchemaEnable true If true add the schema.html microformat to <head> Note 14
microformatsTwitterCardEnable true If true add twitter_cards.html microformat to <head> Note 15
multipleH1ErrorIgnore true If false and there would be multiple <h1> elements on a page, error the build Note 19
multipleH1ErrorFix false If true and there would be multiple <h1> elements on a page, make all but the first an <h2> Note 19
multipleH1ErrorWarn true If true and there would be multiple <h1> elements on a page, issue a warning. Note 19
openGraphType (nil) If set overrides the default type used for Open Graph microformat og:type meta tag Note 16
pageCanonical true Page-level params only. When false omits this page from the sitemap.xml, if applicable
rssIncludeMainArticle false When true include the pages .Content (that is the rendered content from the page’s file such as /content/posts/a-post.md) directly in the RSS feed instead of only a summary or description
summary (nil) If present acts as the summary metadata. Note 18
summaryPreserveHTML false When true preserves any HTML in the Summary Note 18
summaryRenderMarkdown true When true render any Markdown in the Summary Note 18
tags (nil) Should be an array of tags associated with the page. Often also rendered on the page and/or listings by themes. By default is a Taxonomy
taxCanonical false When true includes this taxonomy or term page in the sitemap.xml, if applicable
title (nil) Page param. When present is the title of the page. Note 20
title (nil) Site configuration. When present is the title of the website. Note 21
toCanonical (nil) If pageCanonical is false then sets the <link rel='canonical' href=…> href to value of toCanonical

A note on <head> generation

This theme includes a number of ‘helper’ partials under layouts/partials/helpers/head (called via {{ partial "helpers/head/<name-of-partial>.html" }}) which are intended to assist in populating the contents of the <head> element on your page.

An example generation of <head> using these helpers can be found in the exampleSite source code under /layouts/partials/head.html (which is in turn called by the theme’s layouts/_default/baseof.html).

A note on CSS generation

It is expected that layouts/partial/helpers/head/resources-pipes.html will not be used by consumers of this module, and that instead handling for the CSS, scripts and so on will use code more suitable for the consumer’s production and/or development situation.

That is, it is expected the module consumer will use their own version of resources-pipes.html that overrides the one from this module.

A note on metadata generation

In general metadata can be gathered and accessed by consumers of the module by issuing a partial call such as

{{- $metadataGathered := partial "helpers/return-metadata" ( dict "page" .Page "requestedData" (slice "description" "keywords") ) -}}

Where description and keywords Note 10 are the metadata types we are gathering (see Features for the list of metadata gathered by this module).

Then to use the description (for example):

{{- with $metadataGathered.description }}
    <meta name="description" content="{{ . }}">
{{- end -}}

or

{{- with (index $metadataGathered "description") }}
    <meta name="description" content="{{ . }}">
{{- end -}}

The layouts/partials/helpers/head/metadata.html in this theme gathers and directly adds to <head> description and keywords metadata Note 10. In addition it adds the generator meta tag (using the command hugo.Generator) and also pulls in layouts/partials/helpers/head/microformats.html (see below).

Notes on Date, Expiry, PublishDate, Lastmod

date-created, date-expired, date-published, and date-modified metadata items

Contributions welcome

If your issue can’t be found when searching both open and closed issues, please add it!

Please check open issues on danielfdickinson/metadata-mod-hugo-dfd for enhancements and bugs that you would like resolved, write the fix, and submit a PR!

Adding and improving documention is always handy as well.

Support and general questions

Please use GitHub Discussions for support and general questions.


End notes

Note 1

From frontmatter

Note 2

See DFDs Hugo metadata image module

Note 3

Article or website, depending on frontmatter

Note 4

Other URLs such as those for media-image may have their own secure URL as a part of the microformat

Note 5

Depending on frontmatter and site config

Note 6

Note 7

Microformats are used by search engines and other automated page handling software including for displaying website ‘cards’ (image and summary of a page/site in a box on other sites, such as Discourse forum).

Note 8

When using enableRobotsTXT = true and the default of overriding the robots.txt template with the one from this repo, if disableKinds includes "sitemap" (e.g. disableKinds = ["RSS","sitemap"]) then you will also need to add the following to your config.toml:

[sitemap]
    filename = ""

to avoid the generated robots.txt (/public/robots.txt from your project root in the default configuration) containing the following type of line

Sitemap: <your baseURL from config.toml>

instead of it being omitted from robots.txt.

Note 9

If emptyElementStyle is set to self-close in params (site or per-page), then empty tags produced by this module use ‘self-closing’ form (see above), otherwise ‘void style’ (see above). (Note 6)

For example, with toml for the site as

[params]
     emptyElementStyle = "self-close"

you get

    <meta name="generator" content="Hugo 0.91.2" />
    <meta name="keywords" content="Placeholder" />

while not configuring emptyElementStyle produces

    <meta name="generator" content="Hugo 0.91.2">
    <meta name="keywords" content="Placeholder">

in the ‘Test of metadata for <head>’ section of the page from exampleSite/docs/placeholder.md as the generated /docs/placeholder.

Note 10

Note 11

The layouts/partials/helpers/head/microformats.html in this theme is wrapped in a check for a page or site-level microformatsEnable param which defaults true and pulls in layouts/partials/lib-output/microformats/<microformat_type> where <microformat_type> are each the following four types:

Note 12

Facebook microformat

This is only used if .Site.Social.facebook_admin is defined (via the [social] configuration option in config.toml).

Note 13

Open Graph microformat

This outputs Open Graph protocol microformat meta tags. There are too many to list here, so for details see layouts/partials/helpers/lib-output/microformats/opengraph.html in the source.

Note 14

Schema microformat

This outputs a limited subset of Schema microformat meta tags. There are too many to list here, so for details see layouts/partials/helpers/lib-output/microformats/schema.html in the source.

Note 15

Twitter cards microformat

This outputs Twitter Card microformat meta tags. There are too many to list here, so for details see layouts/partials/helpers/lib-output/microformats/schema.html in the source.

Note 16

Open Graph type (og:type meta tag) defaults to article for most pages except the home page or pages with no PublishDate is article. For the exceptions the the default is type website. See Object Types in the Open Graph Protocol.

Note 17

Note 18

Note 19

Note 20

Page title (name/title/title-page) discovery and use

Note 21

Site title (site_name/title-site) title discovery and use

Metadata gather test

Test of metadata for <head>


    
    <meta name="generator" content="Hugo 0.101.0">
    <meta name="description" content="Basic documentation for metadata-mod-hugo-dfd, a Hugo module by Daniel F. Dickinson for handling page metadata.">
    <meta name="keywords" content="HOWTO">
    <meta property="og:title" content="Hugo DFD Metadata Module README">
    <meta property="og:description" content="Basic documentation for metadata-mod-hugo-dfd, a Hugo module by Daniel F. Dickinson for handling page metadata.">
    <meta property="og:type" content="article">
    <meta property="og:url" content="https://metadata-mod.wildtechgarden.ca/docs/readme/">
    <meta property="article:created_time" content="2022-08-01T19:20:51+00:00">
    <meta property="article:published_time" content="2022-08-01T19:20:51+00:00">
    <meta property="article:modified_time" content="2022-08-01T19:20:51+00:00">
    <meta property="article:section" content="docs">
    <meta property="article:tag" content="HOWTO">
    <meta property="og:locale" content="en">
    <meta property="og:site_name" content="DFD Hugo Metadata Module">
    <meta itemprop="name" content="Hugo DFD Metadata Module README">
    <meta itemprop="description" content="Basic documentation for metadata-mod-hugo-dfd, a Hugo module by Daniel F. Dickinson for handling page metadata.">
    <meta itemprop="keywords" content="HOWTO">
    <meta name="twitter:card" content="summary">
    <meta name="twitter:title" content="Hugo DFD Metadata Module README">
    <meta name="twitter:description" content="Basic documentation for metadata-mod-hugo-dfd, a Hugo module by Daniel F. Dickinson for handling page metadata.">