hugo/docs/content/en/templates/internal.md
2021-03-03 13:30:06 +01:00

7.6 KiB

title linktitle description date publishdate lastmod categories keywords menu weight sections_weight draft aliases toc wip
Internal Templates Internal Templates Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites. 2017-03-06 2017-03-06 2017-03-06
templates
internal
analytics
docs
parent weight
templates 168
168 168 false
true true

{{% warning %}} While the following internal templates are called similar to partials, they do not observe the partial template lookup order. {{% /warning %}}

Google Analytics

Hugo ships with internal templates for Google Analytics tracking, including both synchronous and asynchronous tracking codes. As well as support for both v3 and v4 of Google Analytics.

Configure Google Analytics

Provide your tracking id in your configuration file:

Google Analytics v3 (analytics.js) {{< code-toggle file="config" >}} googleAnalytics = "UA-PROPERTY_ID" {{</ code-toggle >}}

Google Analytics v4 (gtag.js) {{< code-toggle file="config" >}} googleAnalytics = "G-MEASUREMENT_ID" {{</ code-toggle >}}

Use the Google Analytics Template

You can then include the Google Analytics internal template:

{{ template "_internal/google_analytics.html" . }}
{{ template "_internal/google_analytics_async.html" . }}

When using Google Analytics v4 use _internal/google_analytics.html.

A .Site.GoogleAnalytics variable is also exposed from the config.

Disqus

Hugo also ships with an internal template for Disqus comments, a popular commenting system for both static and dynamic websites. In order to effectively use Disqus, you will need to secure a Disqus "shortname" by signing up for the free service.

Configure Disqus

To use Hugo's Disqus template, you first need to set a single value in your site's config.toml or config.yml:

{{< code-toggle file="config" >}} disqusShortname = "yourdiscussshortname" {{</ code-toggle >}}

You also have the option to set the following in the front matter for a given piece of content:

  • disqus_identifier
  • disqus_title
  • disqus_url

Use the Disqus Template

To add Disqus, include the following line in templates where you want your comments to appear:

{{ template "_internal/disqus.html" . }}

A .Site.DisqusShortname variable is also exposed from the config.

Conditional Loading of Disqus Comments

Users have noticed that enabling Disqus comments when running the Hugo web server on localhost (i.e. via hugo server) causes the creation of unwanted discussions on the associated Disqus account.

You can create the following layouts/partials/disqus.html:

{{< code file="layouts/partials/disqus.html" download="disqus.html" >}}

comments powered by Disqus {{< /code >}}

The if statement skips the initialization of the Disqus comment injection when you are running on localhost.

You can then render your custom Disqus partial template as follows:

{{ partial "disqus.html" . }}

Open Graph

An internal template for the Open Graph protocol, metadata that enables a page to become a rich object in a social graph. This format is used for Facebook and some other sites.

Configure Open Graph

Hugo's Open Graph template is configured using a mix of configuration variables and front-matter on individual pages.

{{< code-toggle file="config" >}} [params] title = "My cool site" images = ["site-feature-image.jpg"] description = "Text about my cool site" [taxonomies] series = "series" {{</ code-toggle >}}

{{< code-toggle file="content/blog/my-post" >}} title = "Post title" description = "Text about this post" date = "2006-01-02" images = ["post-cover.png"] audio = [] videos = [] series = [] tags = [] {{</ code-toggle >}}

Hugo uses the page title and description for the title and description metadata. The first 6 URLs from the images array are used for image metadata.

Various optional metadata can also be set:

  • Date, published date, and last modified data are used to set the published time metadata if specified.
  • audio and videos are URL arrays like images for the audio and video metadata tags, respectively.
  • The first 6 tags on the page are used for the tags metadata.
  • The series taxonomy is used to specify related "see also" pages by placing them in the same series.

If using YouTube this will produce a og:video tag like <meta property="og:video" content="url">. Use the https://youtu.be/<id> format with YouTube videos (example: https://youtu.be/qtIqKaDlqXo).

Use the Open Graph Template

To add Open Graph metadata, include the following line between the <head> tags in your templates:

{{ template "_internal/opengraph.html" . }}

Twitter Cards

An internal template for Twitter Cards, metadata used to attach rich media to Tweets linking to your site.

Configure Twitter Cards

Hugo's Twitter Card template is configured using a mix of configuration variables and front-matter on individual pages.

{{< code-toggle file="config" >}} [params] images = ["site-feature-image.jpg"] description = "Text about my cool site" {{</ code-toggle >}}

{{< code-toggle file="content/blog/my-post" >}} title = "Post title" description = "Text about this post" images = ["post-cover.png"] {{</ code-toggle >}}

If images aren't specified in the page front-matter, then hugo searches for image page resources with feature, cover, or thumbnail in their name. If no image resources with those names are found, the images defined in the site config are used instead. If no images are found at all, then an image-less Twitter summary card is used instead of summary_large_image.

Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given.

Use the Twitter Cards Template

To add Twitter card metadata, include the following line between the <head> tags in your templates:

{{ template "_internal/twitter_cards.html" . }}

The Internal Templates

  • _internal/disqus.html
  • _internal/google_news.html
  • _internal/google_analytics.html
  • _internal/google_analytics_async.html
  • _internal/opengraph.html
  • _internal/pagination.html
  • _internal/schema.html
  • _internal/twitter_cards.html