diff options
Diffstat (limited to 'docs/content/en/variables')
| -rw-r--r-- | docs/content/en/variables/_index.md | 23 | ||||
| -rw-r--r-- | docs/content/en/variables/files.md | 54 | ||||
| -rw-r--r-- | docs/content/en/variables/git.md | 58 | ||||
| -rw-r--r-- | docs/content/en/variables/menus.md | 128 | ||||
| -rw-r--r-- | docs/content/en/variables/page.md | 299 | ||||
| -rw-r--r-- | docs/content/en/variables/pages.md | 30 | ||||
| -rw-r--r-- | docs/content/en/variables/shortcodes.md | 48 | ||||
| -rw-r--r-- | docs/content/en/variables/site.md | 135 | ||||
| -rw-r--r-- | docs/content/en/variables/sitemap.md | 32 | ||||
| -rw-r--r-- | docs/content/en/variables/taxonomy.md | 84 |
10 files changed, 891 insertions, 0 deletions
diff --git a/docs/content/en/variables/_index.md b/docs/content/en/variables/_index.md new file mode 100644 index 000000000..382ee25d4 --- /dev/null +++ b/docs/content/en/variables/_index.md @@ -0,0 +1,23 @@ +--- +title: Variables and Params +linktitle: Variables Overview +description: Page-, file-, taxonomy-, and site-level variables and parameters available in templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [variables,params,values,globals] +draft: false +menu: + docs: + parent: "variables" + weight: 1 +weight: 01 #rem +sections_weight: 01 +aliases: [/templates/variables/] +toc: false +--- + +Hugo's templates are context aware and make a large number of values available to you as you're creating views for your website. + +[Go templates]: /templates/introduction/ "Understand context in Go templates by learning the language's fundamental templating functions." diff --git a/docs/content/en/variables/files.md b/docs/content/en/variables/files.md new file mode 100644 index 000000000..d8f3daece --- /dev/null +++ b/docs/content/en/variables/files.md @@ -0,0 +1,54 @@ +--- +title: File Variables +linktitle: +description: "You can access filesystem-related data for a content file in the `.File` variable." +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [files] +draft: false +menu: + docs: + parent: "variables" + weight: 40 +weight: 40 +sections_weight: 40 +aliases: [/variables/file-variables/] +toc: false +--- + +{{% note "Rendering Local Files" %}} +For information on creating shortcodes and templates that tap into Hugo's file-related feature set, see [Local File Templates](/templates/files/). +{{% /note %}} + +The `.File` object contains the following fields: + +.File.Path +: the original relative path of the page, relative to the content dir (e.g., `posts/foo.en.md`) + +.File.LogicalName +: the name of the content file that represents a page (e.g., `foo.en.md`) + +.File.TranslationBaseName +: the filename without extension or optional language identifier (e.g., `foo`) + +.File.ContentBaseName +: is a either TranslationBaseName or name of containing folder if file is a leaf bundle. + +.File.BaseFileName +: the filename without extension (e.g., `foo.en`) + +.File.Ext +: the file extension of the content file (e.g., `md`). + +.File.Lang +: the language associated with the given file if Hugo's [Multilingual features][multilingual] are enabled (e.g., `en`) + +.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/`). Note that the path separator (`\` or `/`) could be dependent on the operating system. + +.File.UniqueID +: the MD5-checksum of the content file's path. + +[Multilingual]: /content-management/multilingual/ diff --git a/docs/content/en/variables/git.md b/docs/content/en/variables/git.md new file mode 100644 index 000000000..58a285fd9 --- /dev/null +++ b/docs/content/en/variables/git.md @@ -0,0 +1,58 @@ +--- +title: Git Info Variables +linktitle: Git Variables +description: Get the last Git revision information for every content file. +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +categories: [variables and params] +keywords: [git] +draft: false +menu: + docs: + parent: "variables" + weight: 70 +weight: 70 +sections_weight: 70 +aliases: [/extras/gitinfo/] +toc: false +wip: false +--- + +{{% note "`.GitInfo` Performance Considerations" %}} +Hugo's Git integrations should be fairly performant but *can* increase your build time. This will depend on the size of your Git history. +{{% /note %}} + +## `.GitInfo` Prerequisites + +1. The Hugo site must be in a Git-enabled directory. +2. The Git executable must be installed and in your system `PATH`. +3. The `.GitInfo` feature must be enabled in your Hugo project by passing `--enableGitInfo` flag on the command line or by setting `enableGitInfo` to `true` in your [site's configuration file][configuration]. + +## The `.GitInfo` Object + +The `GitInfo` object contains the following fields: + +.AbbreviatedHash +: the abbreviated commit hash (e.g., `866cbcc`) + +.AuthorName +: the author's name, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap) + +.AuthorEmail +: the author's email address, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap) + +.AuthorDate +: the author date + +.Hash +: the commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`) + +.Subject +: commit message subject (e.g., `tpl: Add custom index function`) + +## `.Lastmod` + +If the `.GitInfo` feature is enabled, `.Lastmod` (on `Page`) is fetched from Git i.e. `.GitInfo.AuthorDate`. This behaviour can be changed by adding your own [front matter configuration for dates](/getting-started/configuration/#configure-front-matter). + +[configuration]: /getting-started/configuration/ diff --git a/docs/content/en/variables/menus.md b/docs/content/en/variables/menus.md new file mode 100644 index 000000000..9b8fe4d49 --- /dev/null +++ b/docs/content/en/variables/menus.md @@ -0,0 +1,128 @@ +--- +title: Menu Entry Properties +linktitle: Menu Entry Properties +description: A menu entry in a menu-template has specific variables and functions to make menu management easier. +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +categories: [variables and params] +keywords: [menus] +draft: false +menu: + docs: + title: "variables defined by a menu entry" + parent: "variables" + weight: 50 +weight: 50 +sections_weight: 50 +aliases: [/variables/menu/] +toc: false +--- + +A **menu entry** has the following properties available that can be used in a +[menu template][menu-template]. + +## Menu Entry Variables + +.Menu +: _string_ <br /> +Name of the **menu** that contains this **menu entry**. + +.URL +: _string_ <br /> +URL that the menu entry points to. The `url` key, if set for the menu entry, +sets this value. If that key is not set, and if the menu entry is set in a page +front-matter, this value defaults to the page's `.RelPermalink`. + +.Page +: _\*Page_ <br /> +Reference to the [page object][page-object] associated with the menu entry. This +will be non-nil if the menu entry is set via a page's front-matter and not via +the site config. + +.PageRef {{< new-in "0.86.0" >}} +: _string_ <br /> Can be set if defined in site config and the menu entry refers to a Page. [site.GetPage](/functions/getpage/) will be used to do the page lookup. If this is set, you don't need to set the `URL`. + +.Name +: _string_ <br /> +Name of the menu entry. The `name` key, if set for the menu entry, sets +this value. If that key is not set, and if the menu entry is set in a page +front-matter, this value defaults to the page's `.LinkTitle`. + +.Identifier +: _string_ <br /> +Value of the `identifier` key if set for the menu entry. This value must be +unique for each menu entry. **It is necessary to set a unique identifier +manually if two or more menu entries have the same `.Name`.** + +.Pre +: _template.HTML_ <br /> +Value of the `pre` key if set for the menu entry. This value typically contains +a string representing HTML. + +.Post +: _template.HTML_ <br /> +Value of the `post` key if set for the menu entry. This value typically contains +a string representing HTML. + +.Weight +: _int_ <br /> +Value of the `weight` key if set for the menu entry. By default the entries in +a menu are sorted ascending by their `weight`. If that key is not set, and if +the menu entry is set in a page front-matter, this value defaults to the page's +`.Weight`. + +.Parent +: _string_ <br /> +Name (or Identifier if present) of this menu entry's parent **menu entry**. The +`parent` key, if set for the menu entry, sets this value. If this key is set, +this menu entry nests under that parent entry, else it nests directly under the +`.Menu`. + +.Children +: _Menu_ <br /> +This value is auto-populated by Hugo. It is a collection of children menu +entries, if any, under the current menu entry. + +## Menu Entry Functions + +Menus also have the following functions available: + +.HasChildren +: _boolean_ <br /> +Returns `true` if `.Children` is non-nil. + +.KeyName +: _string_ <br /> +Returns the `.Identifier` if present, else returns the `.Name`. + +.IsEqual +: _boolean_ <br /> +Returns `true` if the two compared menu entries represent the same menu entry. + +.IsSameResource +: _boolean_ <br /> +Returns `true` if the two compared menu entries have the same `.URL`. + +.Title +: _string_ <br /> +Link title, meant to be used in the `title` attribute of a menu entry's +`<a>`-tags. Returns the menu entry's `title` key if set. Else, if the menu +entry was created through a page's front-matter, it returns the page's +`.LinkTitle`. Else, it just returns an empty string. + +## Other Menu-related Functions + +Additionally, here are some relevant methods available to menus on a page: + +.IsMenuCurrent +: _(menu string, menuEntry *MenuEntry ) boolean_ <br /> +See [`.IsMenuCurrent` method](/functions/ismenucurrent/). + +.HasMenuCurrent +: _(menu string, menuEntry *MenuEntry) boolean_ <br /> +See [`.HasMenuCurrent` method](/functions/hasmenucurrent/). + + +[menu-template]: /templates/menu-templates/ +[page-object]: /variables/page/ diff --git a/docs/content/en/variables/page.md b/docs/content/en/variables/page.md new file mode 100644 index 000000000..b489bd9e2 --- /dev/null +++ b/docs/content/en/variables/page.md @@ -0,0 +1,299 @@ +--- +title: Page Variables +linktitle: +description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [pages] +draft: false +menu: + docs: + title: "variables defined by a page" + parent: "variables" + weight: 20 +weight: 20 +sections_weight: 20 +aliases: [] +toc: true +--- + +The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself. + +{{% note "`.Scratch`" %}} +See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables. +{{% /note %}} + +## Page Variables + +.AlternativeOutputFormats +: contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's `<head>`. (See [Output Formats](/templates/output-formats/).) + +.Aliases +: aliases of this page + +.BundleType +: the [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle. + +.Content +: the content itself, defined below the front matter. + +.Data +: the data specific to this type of page. + +.Date +: the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`. + +.Description +: the description for the page. + +.Draft +: a boolean, `true` if the content is marked as a draft in the front matter. + +.ExpiryDate +: the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`. + +.File +: filesystem-related data for this content file. See also [File Variables][]. + +.FuzzyWordCount +: the approximate number of words in the content. + +.IsHome +: `true` in the context of the [homepage](/templates/homepage/). + +.IsNode +: always `false` for regular content pages. + +.IsPage +: always `true` for regular content pages. + +.IsSection +: `true` if [`.Kind`](/templates/section-templates/#page-kinds) is `section`. + +.IsTranslated +: `true` if there are translations to display. + +.Keywords +: the meta keywords for the content. + +.Kind +: the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `term`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections. + +.Language +: a language object that points to the language's definition in the site `config`. `.Language.Lang` gives you the language code. + +.Lastmod +: the date the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter. + + - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used. + - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead. + +See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo]. + +.LinkTitle +: access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`. + +.Next +: Points up to the next [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath)). Example: `{{with .Next}}{{.Permalink}}{{end}}`. Calling `.Next` from the first page returns `nil`. + +.NextInSection +: Points up to the next [regular page](/variables/site/#site-pages) below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath). Example: `{{with .NextInSection}}{{.Permalink}}{{end}}`. Calling `.NextInSection` from the first page returns `nil`. + +.OutputFormats +: contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).) + +.Pages +: a collection of associated pages. This value will be `nil` within + the context of regular content pages. See [`.Pages`](#pages). + +.Permalink +: the Permanent link for this page; see [Permalinks](/content-management/urls/) + +.Plain +: the Page content stripped of HTML tags and presented as a string. + +.PlainWords +: the slice of strings that results from splitting .Plain into words, as defined in Go's [strings.Fields](https://golang.org/pkg/strings/#Fields). + +.Prev +: Points down to the previous [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath)). Example: `{{if .Prev}}{{.Prev.Permalink}}{{end}}`. Calling `.Prev` from the last page returns `nil`. + +.PrevInSection +: Points down to the previous [regular page](/variables/site/#site-pages) below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath). Example: `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`. Calling `.PrevInSection` from the last page returns `nil`. + +.PublishDate +: the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`. + +.RawContent +: raw markdown content without the front matter. Useful with [remarkjs.com]( +https://remarkjs.com) + +.ReadingTime +: the estimated time, in minutes, it takes to read the content. + +.Resources +: resources such as images and CSS that are associated with this page + +.Ref +: returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.RelPermalink +: the relative permanent link for this page. + +.RelRef +: returns the relative permalink for a given reference (e.g., `RelRef +"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.Site +: see [Site Variables](/variables/site/). + +.Sites +: returns all sites (languages). A typical use case would be to link back to the main language: `<a href="{{ .Sites.First.Home.RelPermalink }}">...</a>`. + +.Sites.First +: returns the site for the first language. If this is not a multilingual setup, it will return itself. + +.Summary +: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code><!--more--></code> at the appropriate place in the content page, or the summary can be written independent of the page text. See [Content Summaries](/content-management/summaries/) for more details. + +.TableOfContents +: the rendered [table of contents](/content-management/toc/) for the page. + +.Title +: the title for this page. + +.Translations +: a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. + +.TranslationKey +: the key used to map language translations of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. + +.Truncated +: a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information. + +.Type +: the [content type](/content-management/types/) of the content (e.g., `posts`). + +.Weight +: assigned weight (in the front matter) to this content, used in sorting. + +.WordCount +: the number of words in the content. + +## Section Variables and Methods + +Also see [Sections](/content-management/sections/). + +{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}} + +## The `.Pages` Variable {#pages} + +`.Pages` is an alias to `.Data.Pages`. It is conventional to use the +aliased form `.Pages`. + +### `.Pages` compared to `.Site.Pages` + +{{< getcontent path="readfiles/pages-vs-site-pages.md" >}} + +## Page-level Params + +Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable. + +``` +--- +title: My First Post +date: 2017-02-20T15:26:23-06:00 +categories: [one] +tags: [two,three,four] +``` + +With the above front matter, the `tags` and `categories` taxonomies are accessible via the following: + +* `.Params.tags` +* `.Params.categories` + +{{% note "Casing of Params" %}} +Page-level `.Params` are *only* accessible in lowercase. +{{% /note %}} + +The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`: + +``` +--- +... +affiliatelink: "http://www.my-book-link.here" +recommendedby: "My Mother" +... +--- +``` + +These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively. + +Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors. + +{{< code file="/themes/yourtheme/layouts/review/single.html" >}} +<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3> +<p>It was recommended by {{ .Params.recommendedby }}.</p> +{{< /code >}} + +This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/): + +{{< output file="yourbaseurl/review/book01/index.html" >}} +<h3><a href="http://www.my-book-link.here">Buy this book</a></h3> +<p>It was recommended by my Mother.</p> +{{< /output >}} + +{{% note %}} +See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content. +{{% /note %}} + +### The `.Param` Method + +In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image): + +``` +{{ $.Param "header_image" }} +``` + +The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your `config`). + +### Access Nested Fields in Front Matter + +When front matter contains nested fields like the following: + +``` +--- +author: + given_name: John + family_name: Feminella + display_name: John Feminella +--- +``` +`.Param` can access these fields by concatenating the field names together with a dot: + +``` +{{ $.Param "author.display_name" }} +``` + +If your front matter contains a top-level key that is ambiguous with a nested key, as in the following case: + +``` +--- +favorites.flavor: vanilla +favorites: + flavor: chocolate +--- +``` + +The top-level key will be preferred. Therefore, the following method, when applied to the previous example, will print `vanilla` and not `chocolate`: + +``` +{{ $.Param "favorites.flavor" }} +=> vanilla +``` + +[gitinfo]: /variables/git/ +[File Variables]: /variables/files/ +[bundle]: {{< relref "content-management/page-bundles" >}} diff --git a/docs/content/en/variables/pages.md b/docs/content/en/variables/pages.md new file mode 100644 index 000000000..79d39a158 --- /dev/null +++ b/docs/content/en/variables/pages.md @@ -0,0 +1,30 @@ +--- +title: Pages Methods +linktitle: +description: Pages is the core page collection in Hugo and has many useful methods. +date: 2019-10-20 +categories: [variables and params] +keywords: [pages] +draft: false +menu: + docs: + title: "methods defined on a page collection" + parent: "variables" + weight: 21 +weight: 21 +sections_weight: 20 +aliases: [/pages] +toc: true +--- + +Also see [List templates](/templates/lists) for an overview of sort methods. + +## .Next PAGE + +`.Next` and `.Prev` on `Pages` work similar to the methods with the same names on `.Page`, but are more flexible (and slightly slower) as they can be used on any page collection. + +`.Next` points **up** to the next page relative to the page sent in as the argument. Example: `{{with .Site.RegularPages.Next . }}{{.RelPermalink}}{{end}}`. Calling `.Next` with the first page in the collection returns `nil`. + +## .Prev PAGE + +`.Prev` points **down** to the previous page relative to the page sent in as the argument. Example: `{{with .Site.RegularPages.Prev . }}{{.RelPermalink}}{{end}}`. Calling `.Prev` with the last page in the collection returns `nil`.
\ No newline at end of file diff --git a/docs/content/en/variables/shortcodes.md b/docs/content/en/variables/shortcodes.md new file mode 100644 index 000000000..14eb2aca2 --- /dev/null +++ b/docs/content/en/variables/shortcodes.md @@ -0,0 +1,48 @@ +--- +title: Shortcode Variables +linktitle: Shortcode Variables +description: Shortcodes can access page variables and also have their own specific built-in variables. +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +categories: [variables and params] +keywords: [shortcodes] +draft: false +menu: + docs: + parent: "variables" + weight: 20 +weight: 20 +sections_weight: 20 +aliases: [] +toc: false +--- + +[Shortcodes][shortcodes] have access to parameters delimited in the shortcode declaration via [`.Get`][getfunction], page- and site-level variables, and also the following shortcode-specific fields: + +.Name +: Shortcode name. + +.Ordinal +: Zero-based ordinal in relation to its parent. If the parent is the page itself, this ordinal will represent the position of this shortcode in the page content. + +.Page +: The owning ´Page`. + +.Parent +: provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root. + +.Position +: Contains [filename and position](https://godoc.org/github.com/gohugoio/hugo/common/text#Position) for the shortcode in a page. Note that this can be relatively expensive to calculate, and is meant for error reporting. See [Error Handling in Shortcodes](/templates/shortcode-templates/#error-handling-in-shortcodes). + +.IsNamedParams +: boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes] + +.Inner +: represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used + +[getfunction]: /functions/get/ +[markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown +[shortcodes]: /templates/shortcode-templates/ + + diff --git a/docs/content/en/variables/site.md b/docs/content/en/variables/site.md new file mode 100644 index 000000000..bdfeb6527 --- /dev/null +++ b/docs/content/en/variables/site.md @@ -0,0 +1,135 @@ +--- +title: Site Variables +linktitle: Site Variables +description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [global,site] +draft: false +menu: + docs: + parent: "variables" + weight: 10 +weight: 10 +sections_weight: 10 +aliases: [/variables/site-variables/] +toc: true +--- + +The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates. + +## Get the Site object from a partial + +All the methods below, e.g. `.Site.RegularPages` can also be reached via the global [`site`](/functions/site/) function, e.g. `site.RegularPages`, which can be handy in partials where the `Page` object isn't easily available. {{< new-in "0.53" >}}. + +## Site Variables List + +.Site.AllPages +: array of all pages, regardless of their translation. + +.Site.Author +: a map of the authors as defined in the site configuration. + +.Site.BaseURL +: the base URL for the site as defined in the site configuration. + +.Site.BuildDrafts +: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration. + +.Site.Copyright +: a string representing the copyright of your website as defined in the site configuration. + +.Site.Data +: custom data, see [Data Templates](/templates/data-templates/). + +.Site.DisqusShortname +: a string representing the shortname of the Disqus shortcode as defined in the site configuration. + +.Site.GoogleAnalytics +: a string representing your tracking code for Google Analytics as defined in the site configuration. + +.Site.Home +: reference to the homepage's [page object](https://gohugo.io/variables/page/) + +.Site.IsMultiLingual +: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information. + +.Site.IsServer +: a boolean to indicate if the site is being served with Hugo's built-in server. See [`hugo server`](/commands/hugo_server/) for more information. + +.Site.Language.Lang +: the language code of the current locale (e.g., `en`). + +.Site.Language.LanguageName +: the full language name (e.g. `English`). + +.Site.Language.Weight +: the weight that defines the order in the `.Site.Languages` list. + +.Site.Language +: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition. + +.Site.LanguageCode +: a string representing the language tag as defined in the site configuration. + +.Site.LanguagePrefix +: this can be used to prefix URLs to point to the correct language. It will even work when only one defined language. See also the functions [absLangURL](/functions/abslangurl/) and [relLangURL](/functions/rellangurl). + +.Site.Languages +: an ordered list (ordered by defined weight) of languages. + +.Site.LastChange +: a string representing the date/time of the most recent change to your site. This string is based on the [`date` variable in the front matter](/content-management/front-matter) of your content pages. + +.Site.Menus +: all of the menus in the site. + +.Site.Pages +: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`](#site-pages). + +.Site.RegularPages +: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`](#site-pages). + +.Site.Sections +: top-level directories of the site. + +.Site.Taxonomies +: the [taxonomies](/taxonomies/usage/) for the entire site. Also see section [Use `.Site.Taxonomies` Outside of Taxonomy Templates](/variables/taxonomy/#use-sitetaxonomies-outside-of-taxonomy-templates). + +.Site.Title +: a string representing the title of the site. + +## The `.Site.Params` Variable + +`.Site.Params` is a container holding the values from the `params` section of your site configuration. + +### Example: `.Site.Params` + +The following `config.[yaml|toml|json]` defines a site-wide param for `description`: + +{{< code-toggle file="config" >}} +baseURL = "https://yoursite.example.com/" + +[params] + description = "Tesla's Awesome Hugo Site" + author = "Nikola Tesla" +{{</ code-toggle >}} + +You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description: + +{{< code file="layouts/partials/head.html" >}} +<meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" /> +{{< /code >}} + +## The `.Site.Pages` Variable {#site-pages} + +### `.Site.Pages` compared to `.Pages` + +{{< getcontent path="readfiles/pages-vs-site-pages.md" >}} + + + + +[config]: /getting-started/configuration/ diff --git a/docs/content/en/variables/sitemap.md b/docs/content/en/variables/sitemap.md new file mode 100644 index 000000000..dd926f2b3 --- /dev/null +++ b/docs/content/en/variables/sitemap.md @@ -0,0 +1,32 @@ +--- +title: Sitemap Variables +linktitle: Sitemap Variables +description: +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +categories: [variables and params] +keywords: [sitemap] +draft: false +menu: + docs: + parent: "variables" + weight: 80 +weight: 80 +sections_weight: 80 +aliases: [] +toc: false +--- + +A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use sitemap templates. They also have the following sitemap-specific variables available to them: + +.Sitemap.ChangeFreq +: the page change frequency + +.Sitemap.Priority +: the priority of the page + +.Sitemap.Filename +: the sitemap filename + +[pagevars]: /variables/page/
\ No newline at end of file diff --git a/docs/content/en/variables/taxonomy.md b/docs/content/en/variables/taxonomy.md new file mode 100644 index 000000000..5bcdffee5 --- /dev/null +++ b/docs/content/en/variables/taxonomy.md @@ -0,0 +1,84 @@ +--- +title: Taxonomy Variables +linktitle: +description: Taxonomy pages are of type `Page` and have all page-, site-, and list-level variables available to them. However, taxonomy terms templates have additional variables available to their templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [taxonomies,terms] +draft: false +menu: + docs: + parent: "variables" + weight: 30 +weight: 30 +sections_weight: 30 +aliases: [] +toc: true +--- + +## Taxonomy Terms Page Variables + +[Taxonomy terms pages][taxonomytemplates] are of the type `Page` and have the following additional variables. + +For example, the following fields would be available in `layouts/_defaults/terms.html`, depending on how you organize your [taxonomy templates][taxonomytemplates]: + +.Data.Singular +: The singular name of the taxonomy (e.g., `tags => tag`) + +.Data.Plural +: The plural name of the taxonomy (e.g., `tags => tags`) + +.Data.Pages +: The list of pages in the taxonomy + +.Data.Terms +: The taxonomy itself + +.Data.Terms.Alphabetical +: The taxonomy terms alphabetized + +.Data.Terms.ByCount +: The Terms ordered by popularity + +Note that `.Data.Terms.Alphabetical` and `.Data.Terms.ByCount` can also be reversed: + +* `.Data.Terms.Alphabetical.Reverse` +* `.Data.Terms.ByCount.Reverse` + +## Use `.Site.Taxonomies` Outside of Taxonomy Templates + +The `.Site.Taxonomies` variable holds all the taxonomies defined site-wide. `.Site.Taxonomies` is a map of the taxonomy name to a list of its values (e.g., `"tags" -> ["tag1", "tag2", "tag3"]`). Each value, though, is not a string but rather a *Taxonomy variable*. + +## The `.Taxonomy` Variable + +The `.Taxonomy` variable, available, for example, as `.Site.Taxonomies.tags`, contains the list of tags (values) and, for each tag, their corresponding content pages. + +### Example Usage of `.Site.Taxonomies` + +The following [partial template][partials] will list all your site's taxonomies, each of their keys, and all the content assigned to each of the keys. For more examples of how to order and render your taxonomies, see [Taxonomy Templates][taxonomytemplates]. + +{{< code file="all-taxonomies-keys-and-pages.html" download="all-taxonomies-keys-and-pages.html" >}} +<section> + <ul> + {{ range $taxonomyname, $taxonomy := .Site.Taxonomies }} + <li><a href="{{ "/" | relLangURL}}{{ $taxonomyname | urlize }}">{{ $taxonomyname }}</a> + <ul> + {{ range $key, $value := $taxonomy }} + <li> {{ $key }} </li> + <ul> + {{ range $value.Pages }} + <li><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li> + {{ end }} + </ul> + {{ end }} + </ul> + </li> + {{ end }} + </ul> +</section> +{{< /code >}} + +[partials]: /templates/partials/ +[taxonomytemplates]: /templates/taxonomy-templates/ |