hugo/docs/content/en/templates/internal.md

213 lines
7.3 KiB
Markdown
Raw Normal View History

---
title: Internal Templates
linktitle: Internal Templates
description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites.
date: 2017-03-06
publishdate: 2017-03-06
lastmod: 2017-03-06
categories: [templates]
keywords: [internal, analytics,]
menu:
docs:
parent: "templates"
weight: 168
weight: 168
sections_weight: 168
draft: false
aliases: []
toc: true
wip: true
---
<!-- reference: https://discourse.gohugo.io/t/lookup-order-for-partials/5705/6
code: https://github.com/gohugoio/hugo/blob/e445c35d6a0c7f5fc2f90f31226cd1d46e048bbc/tpl/template_embedded.go#L147 -->
{{% 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.
### Configure Google Analytics
Provide your tracking id in your configuration file:
{{< code-toggle file="config" >}}
googleAnalytics = "UA-123-45"
{{</ 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" . }}
```
A `.Site.GoogleAnalytics` variable is also exposed from the config.
## Disqus
Hugo also ships with an internal template for [Disqus comments][disqus], 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][disqussignup].
### 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" >}}
<div id="disqus_thread"></div>
<script type="text/javascript">
(function() {
// Don't ever inject Disqus on localhost--it creates unwanted
// discussions from 'localhost:1313' on your Disqus account...
if (window.location.hostname == "localhost")
return;
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
var disqus_shortname = '{{ .Site.DisqusShortname }}';
dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="https://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
{{< /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](https://ogp.me/), 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](/content-management/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](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-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](/content-management/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](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name.
Squashed 'docs/' changes from 341ecabb2..988f7d5c2 988f7d5c2 Document default `enableInlineShortcodes` value 0f604a345 Fix typo in 0.66.0 release note 26fc74fe3 How to access individual EXIF data tags d5d3bad9a Fix localhost links fa6921213 Update index.md 5bf558f78 Release 0.66.0 74ccdaaf5 Merge branch 'temp660' 75faa478b releaser: Add release notes to /docs for release of 0.66.0 c4a4a9922 docs: Regen CLI docs 0624ac198 Add build.UseResourceCacheWhen 58a8d7cd1 Add build options documentation d926c595e fix typo 99713d44b resources: Add basic @import support to resources.PostCSS 224b96cf7 deploy: Implement include/exclude filters for deploy eb1a00050 Adjusting description; WordPress with capitalized P 91d8efa22 Add another tool for migration from the Wordpress a6938a4ac Adjust showcase description a9c0a0a69 Adjust showcase e5af08aa6 Adding Aether as a proposed showcase item. 0013daa34 Add hugo.IsProduction function 34c419ef3 tpl: Add math.Sqrt 5bdab0ebd Update minification.md 9039332e2 Hugo 0.65.3 1400caf3a Merge branch 'temp653' 9796bb337 releaser: Add release notes to /docs for release of 0.65.3 65b26598f Fix typo 23aa57d80 Fix crashes for 404 in IsAncestor etc. 42c54bc6c 0.65.2 67fd5c1f6 Merge branch 'temp652' d820ac017 releaser: Add release notes to /docs for release of 0.65.2 51f0888ff Release 0.65.1 91e95260c releaser: Add release notes to /docs for release of 0.65.1 1880ebf05 fix broken link on internal.md ffaa33889 Update migrations.md de4d64675 Another tool for migration from Medium platform 90b178d77 releaser: Add release notes to /docs for release of 0.65.1 6925cda30 Handle corner case with rendering text as code in URL 3cb4b19dd Release 0.65.0 7a600cb99 Merge branch 'temp650' ef9531ff6 releaser: Add release notes to /docs for release of 0.65.0 9bc19606f docs: Regenerate CLI docs d4a886ed2 Add Page.GetTerms a3bf273a5 fix broken link on use-modules.md 001f52f4e Fix mage URL in development.md eef72e887 Merge commit '4b670bc8cc38103c2c60e5090c2f56bf30832b8d' b18a76631 commands: Support "hugo mod get -u ./..." git-subtree-dir: docs git-subtree-split: 988f7d5c2d7a1d40ec2c8ab961cb5a4e41b5bd4c
2020-03-09 15:19:32 -04:00
If no image resources with those names are found, the images defined in the [site config](/getting-started/configuration/) 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`
[disqus]: https://disqus.com
[disqussignup]: https://disqus.com/profile/signup/