diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-10-29 11:23:25 +0300 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-10-29 11:23:25 +0300 |
commit | 4b2738d87108ac7254b5e18ba842edb838affff4 (patch) | |
tree | 3fcc240051335eb890eb0ec838d71943b12b7eae /docs/content/en/templates | |
parent | 9c88a8a55adf7779039504fa77d74ec80d658c40 (diff) | |
parent | 74309fe5699a595080fdb3a14711e0869babce99 (diff) |
Merge commit '74309fe5699a595080fdb3a14711e0869babce99'
Diffstat (limited to 'docs/content/en/templates')
-rw-r--r-- | docs/content/en/templates/internal.md | 83 | ||||
-rw-r--r-- | docs/content/en/templates/output-formats.md | 2 | ||||
-rw-r--r-- | docs/content/en/templates/shortcode-templates.md | 14 |
3 files changed, 98 insertions, 1 deletions
diff --git a/docs/content/en/templates/internal.md b/docs/content/en/templates/internal.md index 7fbfec43c..fdec63c57 100644 --- a/docs/content/en/templates/internal.md +++ b/docs/content/en/templates/internal.md @@ -50,6 +50,8 @@ You can then include the Google Analytics internal template: {{ 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]. @@ -76,6 +78,8 @@ To add Disqus, include the following line in templates where you want your comme {{ 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. @@ -110,6 +114,85 @@ You can then render your custom Disqus partial template as follows: {{ partial "disqus.html" . }} ``` +## Open Graph +An internal template for the [Open Graph protocol](http://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 = [] +video = [] +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 `video` 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. + +### 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. +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` diff --git a/docs/content/en/templates/output-formats.md b/docs/content/en/templates/output-formats.md index ff286c9d2..37c48b75e 100644 --- a/docs/content/en/templates/output-formats.md +++ b/docs/content/en/templates/output-formats.md @@ -143,7 +143,7 @@ This can be changed by defining an `outputs` list of output formats in either the `Page` front matter or in the site configuration (either for all sites or per language). -Example from site config file`: +Example from site config file: {{< code-toggle file="config" >}} [outputs] diff --git a/docs/content/en/templates/shortcode-templates.md b/docs/content/en/templates/shortcode-templates.md index 67e54089f..ce58c686e 100644 --- a/docs/content/en/templates/shortcode-templates.md +++ b/docs/content/en/templates/shortcode-templates.md @@ -34,6 +34,14 @@ Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, H To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose. +You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g: + +``` +{{< boxes/square >}} +``` + +Note the forward slash. + ### Shortcode Template Lookup Order Shortcode templates have a simple [lookup order][]: @@ -71,6 +79,12 @@ To access a parameter by position, use the `.Get` followed by a numeric position {{ .Get 0 }} ``` +For the second position, you would just use: + +``` +{{ .Get 1 }} +``` + `with` is great when the output depends on a parameter being set: ``` |