mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-09 19:24:47 -04:00
Joe Mooring
Bjørn Erik Pedersen
parent
df31318d1c
commit
f9b5938dde
@ -14,7 +14,10 @@ toc: true
|
||||
|
||||
## GoAT diagrams (ASCII)
|
||||
|
||||
Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
|
||||
Hugo natively supports [GoAT] diagrams with an [embedded code block render hook]. This means that this code block:
|
||||
|
||||
[GoAT]: https://github.com/bep/goat
|
||||
[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
|
||||
|
||||
````txt
|
||||
```goat
|
||||
|
||||
@ -70,13 +70,17 @@ The `<` character indicates that the shortcode's inner content does *not* need f
|
||||
|
||||
You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
|
||||
|
||||
## Use Hugo's built-in shortcodes
|
||||
## Embedded shortcodes
|
||||
|
||||
Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your Markdown content clean.
|
||||
Use these embedded shortcodes as needed.
|
||||
|
||||
### `figure`
|
||||
### figure
|
||||
|
||||
`figure` is an extension of the image syntax in Markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl figure %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `figure` shortcode can use the following named parameters:
|
||||
|
||||
@ -119,13 +123,13 @@ attr
|
||||
attrlink
|
||||
: If the attribution text needs to be hyperlinked, URL of the destination.
|
||||
|
||||
#### Example `figure` input
|
||||
Example usage:
|
||||
|
||||
{{< code file=figure-input-example.md >}}
|
||||
```text
|
||||
{{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
#### Example `figure` output
|
||||
Rendered:
|
||||
|
||||
```html
|
||||
<figure>
|
||||
@ -134,7 +138,13 @@ attrlink
|
||||
</figure>
|
||||
```
|
||||
|
||||
### `gist`
|
||||
### gist
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl gist %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a GitHub [gist] with this URL:
|
||||
|
||||
@ -144,7 +154,7 @@ To display a GitHub [gist] with this URL:
|
||||
https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
|
||||
@ -164,7 +174,13 @@ Rendered:
|
||||
|
||||
{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}
|
||||
|
||||
### `highlight`
|
||||
### highlight
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl highlight %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a highlighted code sample:
|
||||
|
||||
@ -204,8 +220,13 @@ Rendered:
|
||||
{{ end }}
|
||||
{{< /highlight >}}
|
||||
|
||||
### `instagram`
|
||||
### instagram
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl instagram %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display an Instagram post with this URL:
|
||||
|
||||
@ -213,7 +234,7 @@ To display an Instagram post with this URL:
|
||||
https://www.instagram.com/p/CxOWiQNP2MO/
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* instagram CxOWiQNP2MO */>}}
|
||||
@ -223,53 +244,100 @@ Rendered:
|
||||
|
||||
{{< instagram CxOWiQNP2MO >}}
|
||||
|
||||
### `param`
|
||||
### param
|
||||
|
||||
Gets a value from the current `Page's` parameters set in front matter, with a fallback to the site parameter value. It will log an `ERROR` if the parameter with the given key could not be found in either.
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
```sh
|
||||
[source code]: {{% eturl param %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `param` shortcode renders a parameter from the page's front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
{{</* param testparam */>}}
|
||||
```
|
||||
|
||||
Since `testparam` is a parameter defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
|
||||
Access nested values by [chaining] the [identifiers]:
|
||||
|
||||
{{< param testparam >}}
|
||||
[chaining]: /getting-started/glossary/#chain
|
||||
[identifiers]: /getting-started/glossary/#identifier
|
||||
|
||||
To access deeply nested parameters, use "dot syntax", e.g:
|
||||
|
||||
```sh
|
||||
{{</* param "my.nested.param" */>}}
|
||||
```text
|
||||
{{</* param my.nested.param */>}}
|
||||
```
|
||||
|
||||
### `ref` and `relref`
|
||||
|
||||
These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
|
||||
|
||||
`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
|
||||
### ref
|
||||
|
||||
{{% note %}}
|
||||
Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
|
||||
To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
Always use the `{{%/* */%}}` notation when calling this shortcode.
|
||||
|
||||
[source code]: {{% eturl ref %}}
|
||||
{{% /note %}}
|
||||
|
||||
`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
|
||||
The `ref` shortcode returns the permalink of the given page reference.
|
||||
|
||||
#### Example `ref` and `relref` input
|
||||
Example usage:
|
||||
|
||||
```go-html-template
|
||||
[Neat]({{</* ref "blog/neat.md" */>}})
|
||||
[Who]({{</* relref "about.md#who" */>}})
|
||||
```text
|
||||
[Post 1]({{%/* ref "/posts/post-1" */%}})
|
||||
[Post 1]({{%/* ref "/posts/post-1.md" */%}})
|
||||
[Post 1]({{%/* ref "/posts/post-1#foo" */%}})
|
||||
[Post 1]({{%/* ref "/posts/post-1.md#foo" */%}})
|
||||
```
|
||||
|
||||
#### Example `ref` and `relref` output
|
||||
|
||||
Assuming that standard Hugo pretty URLs are turned on.
|
||||
Rendered:
|
||||
|
||||
```html
|
||||
<a href="https://example.org/blog/neat">Neat</a>
|
||||
<a href="/about/#who">Who</a>
|
||||
<a href="http://example.org/posts/post-1/">Post 1</a>
|
||||
<a href="http://example.org/posts/post-1/">Post 1</a>
|
||||
<a href="http://example.org/posts/post-1/#foo">Post 1</a>
|
||||
<a href="http://example.org/posts/post-1/#foo">Post 1</a>
|
||||
```
|
||||
|
||||
### `tweet`
|
||||
### relref
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
Always use the `{{%/* */%}}` notation when calling this shortcode.
|
||||
|
||||
[source code]: {{% eturl relref %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `relref` shortcode returns the permalink of the given page reference.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
[Post 1]({{%/* relref "/posts/post-1" */%}})
|
||||
[Post 1]({{%/* relref "/posts/post-1.md" */%}})
|
||||
[Post 1]({{%/* relref "/posts/post-1#foo" */%}})
|
||||
[Post 1]({{%/* relref "/posts/post-1.md#foo" */%}})
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
```html
|
||||
<a href="/posts/post-1/">Post 1</a>
|
||||
<a href="/posts/post-1/">Post 1</a>
|
||||
<a href="/posts/post-1/#foo">Post 1</a>
|
||||
<a href="/posts/post-1/#foo">Post 1</a>
|
||||
```
|
||||
|
||||
### twitter
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `twitter` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
You may call the `twitter` shortcode by using its `tweet` alias.
|
||||
|
||||
[source code]: {{% eturl twitter %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a Twitter post with this URL:
|
||||
|
||||
@ -277,17 +345,23 @@ To display a Twitter post with this URL:
|
||||
https://twitter.com/SanDiegoZoo/status/1453110110599868418
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
|
||||
{{</* twitter user="SanDiegoZoo" id="1453110110599868418" */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
|
||||
{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}}
|
||||
|
||||
### `vimeo`
|
||||
### vimeo
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl vimeo %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a Vimeo video with this URL:
|
||||
|
||||
@ -295,7 +369,7 @@ To display a Vimeo video with this URL:
|
||||
https://vimeo.com/channels/staffpicks/55073825
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* vimeo 55073825 */>}}
|
||||
@ -306,14 +380,20 @@ Rendered:
|
||||
{{< vimeo 55073825 >}}
|
||||
|
||||
{{% note %}}
|
||||
If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
|
||||
If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
|
||||
|
||||
```go
|
||||
{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
|
||||
```
|
||||
{{% /note %}}
|
||||
|
||||
### `youtube`
|
||||
### youtube
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl vimeo %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `youtube` shortcode embeds a responsive video player for [YouTube videos]. Only the ID of the video is required, e.g.:
|
||||
|
||||
|
||||
@ -423,10 +423,12 @@ Hugo renders alias files before rendering pages. A new page with the previous fi
|
||||
|
||||
### Customize
|
||||
|
||||
Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context:
|
||||
To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the layouts directory. The template receives the following context:
|
||||
|
||||
Permalink
|
||||
: the link to the page being aliased
|
||||
|
||||
Page
|
||||
: the Page data for the page being aliased
|
||||
|
||||
[source code]: {{% eturl alias %}}
|
||||
|
||||
@ -24,13 +24,13 @@ For documentation related to a new feature, please include the documentation cha
|
||||
|
||||
### Markdown
|
||||
|
||||
Please follow these markdown guidelines:
|
||||
Please follow these guidelines:
|
||||
|
||||
- Use [ATX] headings, not [setext] headings, levels 2 through 4
|
||||
- Use [fenced code blocks], not [indented code blocks]
|
||||
- Use hyphens, not asterisks, with unordered [list items]
|
||||
- Use the [note shortcode] instead of blockquotes
|
||||
- Do not mix [raw HTML] within markdown
|
||||
- Do not mix [raw HTML] within Markdown
|
||||
- Do not use bold text instead of a heading or description term (`dt`)
|
||||
- Remove consecutive blank lines (maximum of two)
|
||||
- Remove trailing spaces
|
||||
@ -46,13 +46,14 @@ Please link to the [glossary of terms] when necessary, and use the terms consist
|
||||
- The term "front matter" is two words unless you are referring to the configuration key
|
||||
- Use the word "map" instead of "dictionary"
|
||||
- Use the word "flag" instead of "option" when referring to a command line flag
|
||||
- Capitalize the word "Markdown"
|
||||
|
||||
#### Page titles and headings
|
||||
|
||||
Please follow these guidelines for page titles and headings:
|
||||
|
||||
- Use sentence-style capitalization
|
||||
- Avoid markdown in headings and page titles
|
||||
- Avoid formatted strings in headings and page titles
|
||||
- Shorter is better
|
||||
|
||||
#### Use active voice with present tense
|
||||
@ -92,9 +93,9 @@ Other guidelines to consider:
|
||||
- When including code samples, use short snippets that demonstrate the concept.
|
||||
- The Hugo user community is global; use [basic english](https://simple.wikipedia.org/wiki/Basic_English) when possible.
|
||||
|
||||
#### Level 6 markdown headings
|
||||
#### Level 6 headings
|
||||
|
||||
Level 6 markdown headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
|
||||
Level 6 headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
|
||||
|
||||
[glossary]: /getting-started/glossary/
|
||||
|
||||
@ -202,26 +203,6 @@ Rendered:
|
||||
|
||||
These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
|
||||
|
||||
### deprecated-in
|
||||
|
||||
Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
|
||||
|
||||
```text
|
||||
{{%/* deprecated-in 0.120.0 */%}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver/
|
||||
{{%/* /deprecated-in */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{% deprecated-in 0.120.0 %}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver/
|
||||
{{% /deprecated-in %}}
|
||||
|
||||
### code
|
||||
|
||||
Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
|
||||
@ -248,6 +229,43 @@ file
|
||||
fm
|
||||
: (`bool`) Whether the example is front matter. Default is `false`.
|
||||
|
||||
|
||||
### deprecated-in
|
||||
|
||||
Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
|
||||
|
||||
```text
|
||||
{{%/* deprecated-in 0.120.0 */%}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver/
|
||||
{{%/* /deprecated-in */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{% deprecated-in 0.120.0 %}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver/
|
||||
{{% /deprecated-in %}}
|
||||
|
||||
### eturl
|
||||
|
||||
Use the embedded template URL (eturl) shortcode to insert an absolute URL to the source code for an embedded template. The shortcode takes a single argument, the base file name of the template (omit the file extension).
|
||||
|
||||
```text
|
||||
This is a link to the [embedded alias template].
|
||||
|
||||
[embedded alias template]: {{%/* eturl alias */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
This is a link to the [embedded alias template].
|
||||
|
||||
[embedded alias template]: {{% eturl alias %}}
|
||||
|
||||
### new-in
|
||||
|
||||
Use the "new-in" shortcode to indicate a new feature:
|
||||
|
||||
@ -11,10 +11,10 @@ action:
|
||||
toc: true
|
||||
---
|
||||
|
||||
Useful in a code block [render hook], the `diagram.Goat` function converts ASCII art to an SVG diagram, returning a [GoAT] diagram object with the following methods:
|
||||
Useful in a [code block render hook], the `diagram.Goat` function converts ASCII art to an SVG diagram, returning a [GoAT] diagram object with the following methods:
|
||||
|
||||
[GoAT]: https://github.com/blampe/goat#readme
|
||||
[render hook]: /render-hooks/
|
||||
[code block render hook]: /render-hooks/code-blocks/
|
||||
|
||||
Inner
|
||||
: (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper.
|
||||
@ -30,7 +30,9 @@ Height
|
||||
|
||||
## GoAT Diagrams
|
||||
|
||||
Hugo natively supports [GoAT] diagrams.
|
||||
Hugo natively supports [GoAT](https://github.com/bep/goat) diagrams with an [embedded code block render hook].
|
||||
|
||||
[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
|
||||
|
||||
This markdown:
|
||||
|
||||
@ -60,9 +62,7 @@ Which appears in your browser as:
|
||||
'---' '-' '+' '+' '---'
|
||||
```
|
||||
|
||||
To customize rendering, override Hugo's [built-in code block render hook] for GoAT diagrams.
|
||||
|
||||
[built-in code block render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-codeblock-goat.html
|
||||
To customize rendering, override Hugo's [embedded code block render hook] for GoAT diagrams.
|
||||
|
||||
## Code block render hook
|
||||
|
||||
|
||||
@ -133,3 +133,10 @@ Then include this snippet at the bottom of the your base template:
|
||||
See the [diagrams] page for details.
|
||||
|
||||
[diagrams]: /content-management/diagrams/#mermaid-diagrams
|
||||
|
||||
## Embedded
|
||||
|
||||
Hugo includes an [embedded code block render hook]({{% eturl render-image %}}) to render [GoAT diagrams].
|
||||
|
||||
[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
|
||||
[GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii
|
||||
|
||||
@ -118,7 +118,7 @@ wrapStandAloneImageWithinParagraph = false
|
||||
|
||||
Hugo includes an [embedded image render hook] to resolve markdown image destinations. Disabled by default, you can enable it in your site configuration:
|
||||
|
||||
[embedded image render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-image.html
|
||||
[embedded image render hook]: {{% eturl render-image %}}
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.renderHooks.image]
|
||||
|
||||
@ -90,7 +90,7 @@ To include a `rel` attribute set to `external` for external links:
|
||||
|
||||
Hugo includes an [embedded link render hook] to resolve markdown link destinations. Disabled by default, you can enable it in your site configuration:
|
||||
|
||||
[embedded link render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-link.html
|
||||
[embedded link render hook]: {{% eturl render-link %}}
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.renderHooks.link]
|
||||
|
||||
@ -15,35 +15,18 @@ toc: true
|
||||
While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order.
|
||||
{{% /note %}}
|
||||
|
||||
## Google Analytics
|
||||
|
||||
Hugo ships with an internal template supporting [Google Analytics 4].
|
||||
|
||||
[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
|
||||
|
||||
### Configure Google Analytics
|
||||
|
||||
Provide your tracking ID in your configuration file:
|
||||
|
||||
**Google Analytics 4 (gtag.js)**
|
||||
{{< code-toggle file=hugo >}}
|
||||
[services.googleAnalytics]
|
||||
ID = "G-MEASUREMENT_ID"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
### Use the Google Analytics template
|
||||
|
||||
Include the Google Analytics internal template in your templates where you want the code to appear:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/google_analytics.html" . }}
|
||||
```
|
||||
|
||||
To create your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
|
||||
|
||||
## Disqus
|
||||
|
||||
Hugo also ships with an internal template for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up for the free service][disqussignup].
|
||||
{{% note %}}
|
||||
To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
|
||||
|
||||
`{{ partial "disqus.html" . }}`
|
||||
|
||||
[`partial`]: /functions/partials/include/
|
||||
[source code]: {{% eturl disqus %}}
|
||||
{{% /note %}}
|
||||
|
||||
Hugo includes an embedded template for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up for the free service][disqussignup].
|
||||
|
||||
### Configure Disqus
|
||||
|
||||
@ -108,9 +91,53 @@ You can then render your custom Disqus partial template as follows:
|
||||
{{ partial "disqus.html" . }}
|
||||
```
|
||||
|
||||
## Google Analytics
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
|
||||
|
||||
`{{ partial "google_analytics.html" . }}`
|
||||
|
||||
[`partial`]: /functions/partials/include/
|
||||
[source code]: {{% eturl google_analytics %}}
|
||||
{{% /note %}}
|
||||
|
||||
Hugo includes an embedded template supporting [Google Analytics 4].
|
||||
|
||||
[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
|
||||
|
||||
### Configure Google Analytics
|
||||
|
||||
Provide your tracking ID in your configuration file:
|
||||
|
||||
**Google Analytics 4 (gtag.js)**
|
||||
{{< code-toggle file=hugo >}}
|
||||
[services.googleAnalytics]
|
||||
ID = "G-MEASUREMENT_ID"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
### Use the Google Analytics template
|
||||
|
||||
Include the Google Analytics internal template in your templates where you want the code to appear:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/google_analytics.html" . }}
|
||||
```
|
||||
|
||||
To create your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
|
||||
|
||||
## 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.
|
||||
{{% note %}}
|
||||
To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
|
||||
|
||||
`{{ partial "opengraph.html" . }}`
|
||||
|
||||
[`partial`]: /functions/partials/include/
|
||||
[source code]: {{% eturl opengraph %}}
|
||||
{{% /note %}}
|
||||
|
||||
Hugo includes an embedded 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
|
||||
@ -158,9 +185,39 @@ To add Open Graph metadata, include the following line between the `<head>` tags
|
||||
{{ template "_internal/opengraph.html" . }}
|
||||
```
|
||||
|
||||
## Schema
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded Schema template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
|
||||
|
||||
`{{ partial "schema.html" . }}`
|
||||
|
||||
[`partial`]: /functions/partials/include/
|
||||
[source code]: {{% eturl schema %}}
|
||||
{{% /note %}}
|
||||
|
||||
Hugo includes an embedded template to render [microdata] `meta` elements within the `head` element of your templates.
|
||||
|
||||
[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
|
||||
|
||||
To call the embedded template from your templates:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/schema.xml" . }}
|
||||
```
|
||||
|
||||
## Twitter Cards
|
||||
|
||||
An internal template for [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
|
||||
{{% note %}}
|
||||
To override Hugo's embedded Twitter Cards template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
|
||||
|
||||
`{{ partial "twitter_cards.html" . }}`
|
||||
|
||||
[`partial`]: /functions/partials/include/
|
||||
[source code]: {{% eturl twitter_cards %}}
|
||||
{{% /note %}}
|
||||
|
||||
Hugo includes an embedded template for [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
|
||||
metadata used to attach rich media to Tweets linking to your site.
|
||||
|
||||
### Configure Twitter Cards
|
||||
@ -206,16 +263,7 @@ To add Twitter card metadata, include the following line immediately after the `
|
||||
{{ template "_internal/twitter_cards.html" . }}
|
||||
```
|
||||
|
||||
## The internal templates
|
||||
|
||||
The code for these templates is located [here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates).
|
||||
|
||||
* `_internal/disqus.html`
|
||||
* `_internal/google_analytics.html`
|
||||
* `_internal/opengraph.html`
|
||||
* `_internal/pagination.html`
|
||||
* `_internal/schema.html`
|
||||
* `_internal/twitter_cards.html`
|
||||
|
||||
[disqus]: https://disqus.com
|
||||
[disqussignup]: https://disqus.com/profile/signup/
|
||||
|
||||
@ -209,7 +209,7 @@ In order for them to return the output format of the current template file inste
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref):
|
||||
From content files, you can use the `ref` or `relref` shortcodes:
|
||||
|
||||
```go-html-template
|
||||
[Neat]({{</* ref "blog/neat.md" "amp" */>}})
|
||||
|
||||
@ -60,9 +60,16 @@ It is also possible to use the `GroupBy` functions in combination with paginatio
|
||||
|
||||
## Build the navigation
|
||||
|
||||
The `.Paginator` contains enough information to build a paginator interface.
|
||||
{{% note %}}
|
||||
To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
|
||||
|
||||
The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles):
|
||||
`{{ partial "pagination" . }}`
|
||||
|
||||
[`partial`]: /functions/partials/include/
|
||||
[source code]: {{% eturl pagination %}}
|
||||
{{% /note %}}
|
||||
|
||||
The easiest way to add this to your pages is to include the embedded template:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
|
||||
@ -18,7 +18,9 @@ To generate a robots.txt file from a template, change the [site configuration]:
|
||||
enableRobotsTXT = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
By default, Hugo generates robots.txt using an [internal template][internal].
|
||||
By default, Hugo generates robots.txt using an [embedded template].
|
||||
|
||||
[embedded template]: {{% eturl robots %}}
|
||||
|
||||
```text
|
||||
User-agent: *
|
||||
@ -56,4 +58,3 @@ Remember that Hugo copies everything in the [static directory][static] to the ro
|
||||
{{% /note %}}
|
||||
|
||||
[site configuration]: /getting-started/configuration/
|
||||
[internal]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/robots.txt
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: RSS templates
|
||||
description: Use the built-in RSS template, or create your own.
|
||||
description: Use the embedded RSS template, or create your own.
|
||||
categories: [templates]
|
||||
keywords: [rss,xml,templates]
|
||||
menu:
|
||||
@ -25,6 +25,8 @@ term = ['html']
|
||||
|
||||
To disable feed generation for all [page kinds]:
|
||||
|
||||
[page kinds]: /getting-started/glossary/#page-kind
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
disableKinds = ['rss']
|
||||
{{< /code-toggle >}}
|
||||
@ -65,7 +67,10 @@ Hugo will render this to:
|
||||
|
||||
## Custom templates
|
||||
|
||||
Override Hugo's [built-in RSS template] by creating one or more of your own, following the naming conventions as shown in the [template lookup order table].
|
||||
Override Hugo's [embedded RSS template] by creating one or more of your own, following the naming conventions as shown in the [template lookup order].
|
||||
|
||||
[embedded RSS template]: {{% eturl rss %}}
|
||||
[template lookup order] #template-lookup-order
|
||||
|
||||
For example, to use different templates for home, section, taxonomy, and term pages:
|
||||
|
||||
@ -80,10 +85,6 @@ layouts/
|
||||
|
||||
RSS templates receive the `.Page` and `.Site` objects in context.
|
||||
|
||||
[built-in RSS template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml
|
||||
[page kinds]: /getting-started/glossary/#page-kind
|
||||
[template lookup order table]: #template-lookup-order
|
||||
|
||||
## Template lookup order
|
||||
|
||||
The table below shows the RSS template lookup order for the different page kinds. The first listing shows the lookup order when running with a theme (`demoTheme`).
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Create your own shortcodes
|
||||
linkTitle: Shortcode templates
|
||||
description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
|
||||
description: You can extend Hugo's embedded shortcodes by creating your own using the same templating syntax as that for single and list pages.
|
||||
categories: [templates]
|
||||
keywords: [shortcodes,templates]
|
||||
menu:
|
||||
@ -16,12 +16,12 @@ toc: true
|
||||
Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content.
|
||||
|
||||
{{% note %}}
|
||||
Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
|
||||
Hugo also ships with embedded shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
|
||||
{{% /note %}}
|
||||
|
||||
## Create custom shortcodes
|
||||
|
||||
Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
|
||||
Hugo's embedded shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
|
||||
|
||||
{{< youtube Eu4zSaKOY4A >}}
|
||||
|
||||
|
||||
@ -14,14 +14,17 @@ aliases: [/layout/sitemap/,/templates/sitemap/]
|
||||
|
||||
## Overview
|
||||
|
||||
Hugo's built-in sitemap templates conform to v0.9 of the [sitemap protocol].
|
||||
Hugo's embedded sitemap templates conform to v0.9 of the [sitemap protocol].
|
||||
|
||||
With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemap.xml] template.
|
||||
With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemap template].
|
||||
|
||||
With a multilingual project, Hugo generates:
|
||||
|
||||
- A sitemap.xml file in the root of each site (language) using the built-in [sitemap.xml] template
|
||||
- A sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemapindex.xml] template
|
||||
- A sitemap.xml file in the root of each site (language) using the [embedded sitemap template]
|
||||
- A sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemapindex template]
|
||||
|
||||
[embedded sitemap template]: {{% eturl sitemap %}}
|
||||
[embedded sitemapindex template]: {{% eturl sitemapindex %}}
|
||||
|
||||
## Configuration
|
||||
|
||||
@ -75,5 +78,3 @@ disableKinds = ['sitemap']
|
||||
[change frequency]: <https://www.sitemaps.org/protocol.html#changefreqdef>
|
||||
[priority]: <https://www.sitemaps.org/protocol.html#priority>
|
||||
[sitemap protocol]: <https://www.sitemaps.org/protocol.html>
|
||||
[sitemap.xml]: <https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/sitemap.xml>
|
||||
[sitemapindex.xml]: <https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/sitemapindex.xml>
|
||||
|
||||
36
data/embedded_template_urls.toml
Normal file
36
data/embedded_template_urls.toml
Normal file
@ -0,0 +1,36 @@
|
||||
# Used by the embedded template URL (eturl.html) shortcode.
|
||||
# Quoted all keys because some are not valid identifiers.
|
||||
|
||||
# BaseURL
|
||||
'base_url' = 'https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates'
|
||||
|
||||
# Templates
|
||||
'alias' = 'alias.html'
|
||||
'disqus' = 'disqus.html'
|
||||
'google_analytics' = 'google_analytics.html'
|
||||
'opengraph' = 'opengraph.html'
|
||||
'pagination' = 'pagination.html'
|
||||
'schema' = 'schema.html'
|
||||
'twitter_cards' = 'twitter_cards.html'
|
||||
|
||||
'robots' = '_default/robots.txt'
|
||||
'rss' = '_default/rss.xml'
|
||||
'sitemap' = '_default/sitemap.xml'
|
||||
'sitemapindex' = '_default/sitemapindex.xml'
|
||||
|
||||
# Render hooks
|
||||
'render-image' = '_default/_markup/render-image.html'
|
||||
'render-link' = '_default/_markup/render-link.html'
|
||||
'render-codeblock-goat' = '_default/_markup/render-codeblock-goat.html'
|
||||
|
||||
# Shortcodes
|
||||
'figure' = 'shortcodes/figure.html'
|
||||
'gist' = 'shortcodes/gist.html'
|
||||
'highlight' = 'shortcodes/highlight.html'
|
||||
'instagram' = 'shortcodes/instagram.html'
|
||||
'param' = 'shortcodes/param.html'
|
||||
'ref' = 'shortcodes/ref.html'
|
||||
'relref' = 'shortcodes/relref.html'
|
||||
'twitter' = 'shortcodes/twitter.html'
|
||||
'vimeo' = 'shortcodes/vimeo.html'
|
||||
'youtube' = 'shortcodes/youtube.html'
|
||||
36
layouts/shortcodes/eturl.html
Normal file
36
layouts/shortcodes/eturl.html
Normal file
@ -0,0 +1,36 @@
|
||||
{{- /*
|
||||
Renders an absolute URL to the source code for an embedded template.
|
||||
|
||||
Accepts either positional or named parameters, and depends on the
|
||||
embedded_templates.toml file in the data directory.
|
||||
|
||||
@param {string} filename The embedded template's file name, excluding extension.
|
||||
|
||||
@returns template.HTML
|
||||
|
||||
@example {{% et robots.txt %}}
|
||||
@example {{% et filename=robots.txt %}}
|
||||
*/}}
|
||||
|
||||
{{- /* Get parameters. */}}
|
||||
{{- $filename := "" -}}
|
||||
{{- if .IsNamedParams -}}
|
||||
{{- $filename = .Get "filename" -}}
|
||||
{{- else -}}
|
||||
{{- $filename = .Get 0 -}}
|
||||
{{- end -}}
|
||||
|
||||
{{- /* Render. */}}
|
||||
{{- with $filename -}}
|
||||
{{- with site.Data.embedded_template_urls -}}
|
||||
{{- with index . $filename -}}
|
||||
{{- urls.JoinPath site.Data.embedded_template_urls.base_url . -}}
|
||||
{{- else -}}
|
||||
{{- errorf "The %q shortcode was unable to find a URL for the embedded template named %q. Check the name. See %s" $.Name $filename $.Position -}}
|
||||
{{- end -}}
|
||||
{{- else -}}
|
||||
{{- errorf "The %q shortcode was unable to find the embedded_templates data file in the site's data directory. See %s" $.Name $.Position -}}
|
||||
{{- end -}}
|
||||
{{- else -}}
|
||||
{{- errorf "The %q shortcodes requires a named or positional parameter, the file name of the embedded template, excluding its extension. See %s" .Name .Position -}}
|
||||
{{- end -}}
|
||||
Loading…
x
Reference in New Issue
Block a user