internal.md (7888B)
1 ---
2 title: Internal Templates
3 linktitle: Internal Templates
4 description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites.
5 date: 2017-03-06
6 publishdate: 2017-03-06
7 lastmod: 2017-03-06
8 categories: [templates]
9 keywords: [internal, analytics,]
10 menu:
11 docs:
12 parent: "templates"
13 weight: 168
14 weight: 168
15 sections_weight: 168
16 draft: false
17 aliases: []
18 toc: true
19 wip: true
20 ---
21 <!-- reference: https://discourse.gohugo.io/t/lookup-order-for-partials/5705/6
22 code: https://github.com/gohugoio/hugo/blob/e445c35d6a0c7f5fc2f90f31226cd1d46e048bbc/tpl/template_embedded.go#L147 -->
23
24 {{% warning %}}
25 While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order.
26 {{% /warning %}}
27
28 ## Google Analytics
29
30 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.
31
32 ### Configure Google Analytics
33
34 Provide your tracking id in your configuration file:
35
36 **Google Analytics v3 (analytics.js)**
37 {{< code-toggle file="config" >}}
38 googleAnalytics = "UA-PROPERTY_ID"
39 {{</ code-toggle >}}
40
41 **Google Analytics v4 (gtag.js)**
42 {{< code-toggle file="config" >}}
43 googleAnalytics = "G-MEASUREMENT_ID"
44 {{</ code-toggle >}}
45
46 ### Use the Google Analytics Template
47
48 You can then include the Google Analytics internal template:
49
50 ```
51 {{ template "_internal/google_analytics.html" . }}
52 ```
53
54
55 ```
56 {{ template "_internal/google_analytics_async.html" . }}
57 ```
58
59 When using Google Analytics v4 use `_internal/google_analytics.html`.
60
61 A `.Site.GoogleAnalytics` variable is also exposed from the config.
62
63 ## Disqus
64
65 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].
66
67 ### Configure Disqus
68
69 To use Hugo's Disqus template, you first need to set a single configuration value:
70
71 {{< code-toggle file="config" >}}
72 disqusShortname = "your-disqus-shortname"
73 {{</ code-toggle >}}
74
75 You also have the option to set the following in the front matter for a given piece of content:
76
77 * `disqus_identifier`
78 * `disqus_title`
79 * `disqus_url`
80
81 ### Use the Disqus Template
82
83 To add Disqus, include the following line in templates where you want your comments to appear:
84
85 ```
86 {{ template "_internal/disqus.html" . }}
87 ```
88
89 A `.Site.DisqusShortname` variable is also exposed from the config.
90
91 ### Conditional Loading of Disqus Comments
92
93 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.
94
95 You can create the following `layouts/partials/disqus.html`:
96
97 {{< code file="layouts/partials/disqus.html" download="disqus.html" >}}
98 <div id="disqus_thread"></div>
99 <script type="text/javascript">
100
101 (function() {
102 // Don't ever inject Disqus on localhost--it creates unwanted
103 // discussions from 'localhost:1313' on your Disqus account...
104 if (window.location.hostname == "localhost")
105 return;
106
107 var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
108 var disqus_shortname = '{{ .Site.DisqusShortname }}';
109 dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
110 (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
111 })();
112 </script>
113 <noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
114 <a href="https://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
115 {{< /code >}}
116
117 The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`.
118
119 You can then render your custom Disqus partial template as follows:
120
121 ```
122 {{ partial "disqus.html" . }}
123 ```
124
125 ## Open Graph
126 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.
127 This format is used for Facebook and some other sites.
128
129 ### Configure Open Graph
130
131 Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
132
133 {{< code-toggle file="config" >}}
134 [params]
135 title = "My cool site"
136 images = ["site-feature-image.jpg"]
137 description = "Text about my cool site"
138 [taxonomies]
139 series = "series"
140 {{</ code-toggle >}}
141
142 {{< code-toggle file="content/blog/my-post" >}}
143 title = "Post title"
144 description = "Text about this post"
145 date = "2006-01-02"
146 images = ["post-cover.png"]
147 audio = []
148 videos = []
149 series = []
150 tags = []
151 {{</ code-toggle >}}
152
153 Hugo uses the page title and description for the title and description metadata.
154 The first 6 URLs from the `images` array are used for image metadata.
155 If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with filenames matching `*feature*` or `*cover*,*thumbnail*` are used for image metadata.
156
157 Various optional metadata can also be set:
158
159 - Date, published date, and last modified data are used to set the published time metadata if specified.
160 - `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively.
161 - The first 6 `tags` on the page are used for the tags metadata.
162 - The `series` taxonomy is used to specify related "see also" pages by placing them in the same series.
163
164 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`).
165
166 ### Use the Open Graph Template
167
168 To add Open Graph metadata, include the following line between the `<head>` tags in your templates:
169
170 ```
171 {{ template "_internal/opengraph.html" . }}
172 ```
173
174 ## Twitter Cards
175
176 An internal template for [Twitter Cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards),
177 metadata used to attach rich media to Tweets linking to your site.
178
179 ### Configure Twitter Cards
180
181 Hugo's Twitter Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
182
183 {{< code-toggle file="config" >}}
184 [params]
185 images = ["site-feature-image.jpg"]
186 description = "Text about my cool site"
187 {{</ code-toggle >}}
188
189 {{< code-toggle file="content/blog/my-post" >}}
190 title = "Post title"
191 description = "Text about this post"
192 images = ["post-cover.png"]
193 {{</ code-toggle >}}
194
195 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.
196 If no image resources with those names are found, the images defined in the [site config](/getting-started/configuration/) are used instead.
197 If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`.
198
199 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.
200
201 ### Use the Twitter Cards Template
202
203 To add Twitter card metadata, include the following line between the `<head>` tags in your templates:
204
205 ```
206 {{ template "_internal/twitter_cards.html" . }}
207 ```
208
209 ## The Internal Templates
210
211 * `_internal/disqus.html`
212 * `_internal/google_analytics.html`
213 * `_internal/google_analytics_async.html`
214 * `_internal/opengraph.html`
215 * `_internal/pagination.html`
216 * `_internal/schema.html`
217 * `_internal/twitter_cards.html`
218
219 [disqus]: https://disqus.com
220 [disqussignup]: https://disqus.com/profile/signup/