hugo/docs/content/templates/variables.md

247 lines
15 KiB
Markdown
Raw Normal View History

2013-07-06 19:36:30 -04:00
---
2014-05-29 18:42:05 -04:00
aliases:
- /doc/variables/
- /layout/variables/
lastmod: 2016-08-22
2014-05-29 18:42:05 -04:00
date: 2013-07-01
linktitle: Variables
menu:
main:
2014-05-29 18:42:05 -04:00
parent: layout
next: /templates/content
prev: /templates/functions
title: Template Variables
weight: 20
2015-05-22 14:46:09 -04:00
toc: true
---
2013-07-04 11:32:55 -04:00
Hugo makes a set of values available to the templates. Go templates are context based. The following
are available in the context for the templates.
2013-08-17 08:34:25 -04:00
## Page Variables
The following is a list of most of the accessible variables which can be
defined for a piece of content. Many of these will be defined in the front
matter, content or derived from file location.
2015-01-31 15:33:34 -05:00
**See also:** [Scratch](/extras/scratch) for page-scoped writable variables.
**.Title** The title for the content.<br>
**.Content** The content itself, defined below the front matter.<br>
**.Summary** A generated summary of the content for easily showing a snippet in a summary view. Note that the breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page. See [Summaries](/content/summaries/) for more details.<br>
**.Truncated** A boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only if necessary. See [Summaries](/content/summaries/) for more details.<br>
**.Description** The description for the content.<br>
**.Keywords** The meta keywords for this content.<br>
**.Date** The date the content is associated with.<br>
**.Lastmod** The date the content was last modified.<br>
**.PublishDate** The date the content is published on.<br>
**.ExpiryDate** The date where the content is scheduled to expire on.<br>
**.Type** The content [type](/content/types/) (e.g. post).<br>
**.Section** The [section](/content/sections/) this content belongs to.<br>
**.Permalink** The Permanent link for this page.<br>
**.RelPermalink** The Relative permanent link for this page.<br>
**.LinkTitle** Access when creating links to this content. Will use `linktitle` if set in front matter, else `title`.<br>
**.RSSLink** Link to the taxonomies' RSS link.<br>
**.TableOfContents** The rendered table of contents for this content.<br>
**.Prev** Pointer to the previous content (based on pub date).<br>
**.Next** Pointer to the following content (based on pub date).<br>
**.PrevInSection** Pointer to the previous content within the same section (based on pub date). For example, `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`.<br>
**.NextInSection** Pointer to the following content within the same section (based on pub date)<br>
**.FuzzyWordCount** The approximate number of words in the content.<br>
**.WordCount** The number of words in the content.<br>
**.ReadingTime** The estimated time it takes to read the content in minutes.<br>
**.Weight** Assigned weight (in the front matter) to this content, used in sorting.<br>
**.RawContent** Raw Markdown content without the metadata header. Useful with [remarkjs.com](http://remarkjs.com)<br>
**.UniqueID** The MD5-checksum of the page's filename<br>
**.Draft** A boolean, `true` if the content is marked as a draft in the front matter.<br>
**.IsNode** Always false for pages.<br>
**.IsPage** Always true for page.<br>
**.Site** See [Site Variables]({{< relref "#site-variables" >}}) below.<br>
**.Hugo** See [Hugo Variables]({{< relref "#hugo-variables" >}}) below.<br>
**.Translations** A list of translated versions of the current page. See [Multilingual]({{< relref "content/multilingual.md" >}}) for more info. Note that the `Translation` variable is also available on node, e.g. home page etc. <br>
**.IsTranslated** Whether there are any translations to display.<br>
**.Lang** Language taken from the language extension notation. <br>
**.Author** Returns the first listed author for a page<br>
**.Authors** (**note the plural form**) Returns all listed authors for a page in the order they are defined in the front matter.<br>
2013-07-04 11:32:55 -04:00
## Page Params
Any other value defined in the front matter, including taxonomies, will be made available under `.Params`.
For example, the *tags* and *categories* taxonomies are accessed with:
2013-07-04 11:32:55 -04:00
* **.Params.tags**
* **.Params.categories**
**All Params are only accessible using all lowercase characters.**
2013-08-17 08:34:25 -04:00
This is particularly useful for the introduction of user defined fields in content files. For example, a Hugo website on book reviews could have in the front matter of <code>/content/review/book01.md</code>
---
...
affiliatelink: "http://www.my-book-link.here"
recommendedby: "my Mother"
---
Which would then be accessible to a template at `/themes/yourtheme/layouts/review/single.html` through `.Params.affiliatelink` and `.Params.recommendedby`, respectively. Two common situations where these could be introduced are as a value of a certain attribute (like `href=""` below) or by itself to be displayed. Sample syntaxes include:
<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
<p>It was recommended by {{ .Params.recommendedby }}.</p>
which would render
<h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
<p>It was recommended by my Mother.</p>
**See also:** [Archetypes]({{% ref "content/archetypes.md" %}}) for consistency of `Params` across pieces of content.
2015-10-12 00:00:58 -04:00
### Param method
2015-10-24 10:28:55 -04:00
In Hugo you can declare params both for the site and the individual page. A common use case is to have a general value for the site and a more specific value for some of the pages (i.e. an image).
2015-10-12 00:00:58 -04:00
With the `Param` method the most specific value will be selected for you, and it is safe to use it in any template (it's defined on both Page and Node):
```
$.Param "image"
2015-10-12 00:00:58 -04:00
```
2013-08-17 08:34:25 -04:00
## Node Variables
In Hugo, a node is any page not rendered directly by a content file. This
includes taxonomies, lists and the homepage.
2013-08-17 08:34:25 -04:00
2015-01-31 15:33:34 -05:00
**See also:** [Scratch](/extras/scratch) for global node variables.
**.Title** The title for the content.<br>
**.Date** The date the content is published on.<br>
**.Lastmod** The date the content was last modified.<br>
**.Permalink** The Permanent link for this node<br>
**.URL** The relative URL for this node.<br>
**.Ref(ref)** Returns the permalink for `ref`. See [cross-references]({{% ref "extras/crossreferences.md" %}}). Does not handle in-page fragments correctly.<br>
**.RelRef(ref)** Returns the relative permalink for `ref`. See [cross-references]({{% ref "extras/crossreferences.md" %}}). Does not handle in-page fragments correctly.<br>
**.RSSLink** Link to the taxonomies' RSS link.<br>
**.Data** The data specific to this type of node.<br>
2015-12-08 15:54:05 -05:00
**.IsHome** True if the node is the site home page.<br>
**.IsNode** Always true for nodes.<br>
**.IsPage** Always false for nodes.<br>
**.Site** See [Site Variables]({{< relref "#site-variables" >}}) below.<br>
**.Hugo** See [Hugo Variables]({{< relref "#hugo-variables" >}}) below.<br>
**.Translations** A list of translated versions of the current node. All nodes (except the pager nodes) can have translated counter parts. See [Multilingual]({{< relref "content/multilingual.md" >}}) for more info. <br>
**.IsTranslated** Whether there are any translations to display.<br>
**.Lang** The language code of this node.<br>
**.Author** Returns the first defined author, sorted by their weight attribute.<br>
**.Authors** (**note the plural form**) Returns all defined authors, sorted by their weight attribute.<br>
2013-08-17 08:34:25 -04:00
### Taxonomy Terms Node Variables
[Taxonomy Terms](/templates/terms/) pages are of the type "node" and have the following **additional** variables. These are available in `layouts/_defaults/terms.html` for example.
**.Data.Singular** The singular name of the taxonomy<br>
**.Data.Plural** The plural name of the taxonomy<br>
**.Data.Pages** the list of pages in this taxonomy<br>
**.Data.Terms** The taxonomy itself<br>
**.Data.Terms.Alphabetical** The Terms alphabetized<br>
**.Data.Terms.ByCount** The Terms ordered by popularity<br>
The last two can also be reversed: **.Data.Terms.Alphabetical.Reverse**, **.Data.Terms.ByCount.Reverse**.
### Taxonomies elsewhere
The **.Site.Taxonomies** variable holds all taxonomies defines site-wide. It is a map of the taxonomy name to a list of its values. For example: "tags" -> ["tag1", "tag2", "tag3"]. Each value, though, is not a string but rather a [Taxonomy variable](#the-taxonomy-variable).
#### The Taxonomy variable
The Taxonomy variable, available as **.Site.Taxonomies.tags** for example, contains the list of tags (values) and, for each of those, their corresponding content pages.
2013-08-17 08:34:25 -04:00
## Site Variables
2013-07-04 11:32:55 -04:00
Also available is `.Site` which has the following:
**.Site.BaseURL** The base URL for the site as defined in the site configuration file.<br>
2015-11-10 22:31:52 -05:00
**.Site.RSSLink** The URL for the site RSS.<br>
**.Site.Taxonomies** The [taxonomies](/taxonomies/usage/) for the entire site. Replaces the now-obsolete `.Site.Indexes` since v0.11. Also see section [Taxonomies elsewhere](#taxonomies-elsewhere).<br>
**.Site.Pages** Array of all content ordered by Date, newest first. Replaces the now-deprecated `.Site.Recent` starting v0.13. This array contains only the pages in the current language.<br>
**.Site.AllPages** Array of all pages regardless of their translation.<br>
**.Site.Params** A container holding the values from the `params` section of your site configuration file. For example, a TOML config file might look like this:
baseurl = "http://yoursite.example.com/"
[params]
description = "Tesla's Awesome Hugo Site"
author = "Nikola Tesla"
**.Site.Sections** Top level directories of the site.<br>
**.Site.Files** All of the source files of the site.<br>
**.Site.Menus** All of the menus in the site.<br>
**.Site.Title** A string representing the title of the site.<br>
**.Site.Authors** An ordered list (ordered by defined weight) of the authors as defined in the site configuration. Have a look at [acessible attributes](#author-variables).<br>
**.Site.LanguageCode** A string representing the language as defined in the site configuration. This is mostly used to populate the RSS feeds with the right language code.<br>
**.Site.DisqusShortname** A string representing the shortname of the Disqus shortcode as defined in the site configuration.<br>
**.Site.GoogleAnalytics** A string representing your tracking code for Google Analytics as defined in the site configuration.<br>
**.Site.Copyright** A string representing the copyright of your web site as defined in the site configuration.<br>
**.Site.LastChange** A string representing the date/time of the most recent change to your site, based on the [`date` variable]({{< ref "content/front-matter.md#required-variables" >}}) in the front matter of your content pages.<br>
**.Site.Permalinks** A string to override the default permalink format. Defined in the site configuration.<br>
**.Site.BuildDrafts** A boolean (Default: false) to indicate whether to build drafts. Defined in the site configuration.<br>
2015-02-09 10:52:52 -05:00
**.Site.Data** Custom data, see [Data Files](/extras/datafiles/).<br>
**.Site.IsMultiLingual** Whether there are more than one language in this site.<br> See [Multilingual]({{< relref "content/multilingual.md" >}}) for more info.<br>
**.Site.Language** This indicates which language you are currently rendering the website for. This is an object with the attributes set in your language definition in your site config.<br>
**.Site.Language.Lang** The language code of the current locale, e.g. `en`.<br>
**.Site.Language.Weight** The weight that defines the order in the `.Site.Languages` list.<br>
**.Site.Language.LanguageName** The full language name, e.g. `English`.<br>
**.Site.LanguagePrefix** This can be used to prefix theURLs with whats needed to point to the correct language. It will even work when only one language defined. See also the functions [absLangURL and relLangURL]({{< relref "templates/functions.md#abslangurl-rellangurl" >}}).<br>
**.Site.Languages** An ordered list (ordered by defined weight) of languages.<br>
## File Variables
The `.File` variable gives you additional information of a page.
> **Note:** `.File` is only accessible on *Pages* but **not** on *Nodes* (like the homepage and list pages).
Available are the following attributes:
**.File.Path** The original relative path of the page, e.g. `content/posts/foo.md`<br>
**.File.LogicalName** The name of the content file that represents a page, e.g. `foo.md`<br>
**.File.BaseFileName** The filename without extension, e.g. `foo`<br>
**.File.Ext** or **.File.Extension** The file extension of the content file, e.g. `md`<br>
**.File.Dir** Given the path `content/posts/dir1/dir2/`, the relative directory path of the content file will be returned, e.g. `posts/dir1/dir2/`<br>
## Author variables
This variables are used for the author profiles feature. You can find a more in-depth explaination with examples [here]({{< relref "extras/authors.md" >}}).
The `authors` frontmatter variable represents a list of author identifiers. Those identifiers are used to match their corresponding profiles. `.Author` contains the profile associated with the first identifiers in the list.
**.Author.ID** The identifier of an author (a.k.a. the filename of his/her profile)<br>
**.Author.GivenName** or **.Author.FirstName** The author's first name, e.g. Charles<br>
**.Author.FamilyName** or **.Author.LastName** The author's last name, e.g. Dickens<br>
**.Author.DisplayName** The author's full name, e.g. Charles Dickens<br>
**.Author.Thumbnail** A link to a thumbnail of the author. Maybe the relative path to an image in the `static` folder<br>
**.Author.Image** A larger image of the author. Can be stored in the `static` folder as well.<br>
**.Author.Bio** A biography with background information about the author<br>
**.Author.ShortBio** A summarized version of the biography<br>
**.Author.Email** The email of the author<br>
**.Author.Weight** The associated weight of an author. Defines the order of authors in the `.Authors` list (except on pages due to the frontmatter)<br>
**.Author.Social** A container holding the values from the `social` section of the author's profile. For example, a TOML profile (excerpt) might look like this:
[social]
facebook = "charles.dickens"
twitter = "charlesdickens"
**.Author.Params** A container holding the values from the `params` section of the author's file. The values can be arbitrary and depend on the profile. For example, a TOML profile (excerpt) might look like this:
[params]
random = "whatever you want"
**.Author.Social.URL** Takes a social network as argument (as string) and generates the link the account automatically. A list of supported social networks and a template can be found [here]({{< relref "extras/authors.md#linking-social-network-accounts-automatically" >}}).
---
`.Authors` (**note the plural form**) is a list of all author profiles that are mentioned in the `authors` frontmatter variable.
**.Authors.Get** Takes the identifier of an author as argument (as string) and returns an `.Author` object.
## Hugo Variables
Also available is `.Hugo` which has the following:
**.Hugo.Generator** Meta tag for the version of Hugo that generated the site. Highly recommended to be included by default in all theme headers so we can start to track the usage and popularity of Hugo. Unlike other variables it outputs a **complete** HTML tag, e.g. `<meta name="generator" content="Hugo 0.15" />`<br>
**.Hugo.Version** The current version of the Hugo binary you are using e.g. `0.13-DEV`<br>
**.Hugo.CommitHash** The git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247`<br>
**.Hugo.BuildDate** The compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`<br>