github.com/lyeb/hugo@v0.47.1/docs/content/en/variables/page.md (about)

     1  ---
     2  title: Page Variables
     3  linktitle:
     4  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.
     5  date: 2017-02-01
     6  publishdate: 2017-02-01
     7  lastmod: 2017-02-01
     8  categories: [variables and params]
     9  keywords: [pages]
    10  draft: false
    11  menu:
    12    docs:
    13      title: "variables defined by a page"
    14      parent: "variables"
    15      weight: 20
    16  weight: 20
    17  sections_weight: 20
    18  aliases: []
    19  toc: true
    20  ---
    21  
    22  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.
    23  
    24  {{% note "`.Scratch`" %}}
    25  See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables.
    26  {{% /note %}}
    27  
    28  ## Page Variables
    29  
    30  .AlternativeOutputFormats
    31  : 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/).)
    32  
    33  .Content
    34  : the content itself, defined below the front matter.
    35  
    36  .Data
    37  : the data specific to this type of page.
    38  
    39  .Date
    40  : the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`.
    41  
    42  .Description
    43  : the description for the page.
    44  
    45  .Dir
    46  : the path of the folder containing this content file. The path is relative to the `content` folder.
    47  
    48  .Draft
    49  : a boolean, `true` if the content is marked as a draft in the front matter.
    50  
    51  .ExpiryDate
    52  : 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`.
    53  
    54  .File
    55  : filesystem-related data for this content file. See also [File Variables][].
    56  
    57  .FuzzyWordCount
    58  : the approximate number of words in the content.
    59  
    60  .Hugo
    61  : see [Hugo Variables](/variables/hugo/).
    62  
    63  .IsHome
    64  : `true` in the context of the [homepage](/templates/homepage/).
    65  
    66  .IsNode
    67  : always `false` for regular content pages.
    68  
    69  .IsPage
    70  : always `true` for regular content pages.
    71  
    72  .IsTranslated
    73  : `true` if there are translations to display.
    74  
    75  .Keywords
    76  : the meta keywords for the content.
    77  
    78  .Kind
    79  : the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`. 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.
    80  
    81  .Lang
    82  : language taken from the language extension notation.
    83  
    84  .Language
    85  : a language object that points to the language's definition in the site
    86  `config`.
    87  
    88  .Lastmod
    89  : the date the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter.
    90  
    91   - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used.
    92   - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead.
    93  
    94  See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo].
    95  
    96  .LinkTitle
    97  : access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`.
    98  
    99  .Next
   100  : pointer to the following content (based on the `publishdate` field in front matter).
   101  
   102  .NextInSection
   103  : pointer to the following content within the same section (based on `publishdate` field in front matter).
   104  
   105  .OutputFormats
   106  : 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/).)
   107  
   108  .Pages
   109  : a collection of associated pages. This value will be `nil` within
   110    the context of regular content pages. See [`.Pages`](#pages).
   111  
   112  .Permalink
   113  : the Permanent link for this page; see [Permalinks](/content-management/urls/)
   114  
   115  .Plain
   116  : the Page content stripped of HTML tags and presented as a string.
   117  
   118  .PlainWords
   119  : the Page content stripped of HTML as a `[]string` using Go's [`strings.Fields`](https://golang.org/pkg/strings/#Fields) to split `.Plain` into a slice.
   120  
   121  .Prev
   122  : Pointer to the previous content (based on `publishdate` in front matter).
   123  
   124  .PrevInSection
   125  : Pointer to the previous content within the same section (based on `publishdate` in front matter). For example, `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`.
   126  
   127  .PublishDate
   128  : 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`.
   129  
   130  .RSSLink
   131  : link to the taxonomies' RSS link.
   132  
   133  .RawContent
   134  : raw markdown content without the front matter. Useful with [remarkjs.com](
   135  http://remarkjs.com)
   136  
   137  .ReadingTime
   138  : the estimated time, in minutes, it takes to read the content.
   139  
   140  .Ref
   141  : 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/).
   142  
   143  .RelPermalink
   144  : the relative permanent link for this page.
   145  
   146  .RelRef
   147  : returns the relative permalink for a given reference (e.g., `RelRef
   148  "sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
   149  
   150  .Site
   151  : see [Site Variables](/variables/site/).
   152  
   153  .Summary
   154  : a generated summary of the content for easily showing a snippet in a summary view. 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 [Content Summaries](/content-management/summaries/) for more details.
   155  
   156  .TableOfContents
   157  : the rendered [table of contents](/content-management/toc/) for the page.
   158  
   159  .Title
   160  : the title for this page.
   161  
   162  .Translations
   163  : a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
   164  
   165  .Truncated
   166  : 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.
   167  
   168  .Type
   169  : the [content type](/content-management/types/) of the content (e.g., `post`).
   170  
   171  .URL
   172  : the URL for the page relative to the web root. Note that a `url` set directly in front matter overrides the default relative URL for the rendered page.
   173  
   174  .UniqueID
   175  : the MD5-checksum of the content file's path.
   176  
   177  .Weight
   178  : assigned weight (in the front matter) to this content, used in sorting.
   179  
   180  .WordCount
   181  : the number of words in the content.
   182  
   183  ## Section Variables and Methods
   184  
   185  Also see [Sections](/content-management/sections/).
   186  
   187  {{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
   188  
   189  ## The `.Pages` Variable {#pages}
   190  
   191  `.Pages` is an alias to `.Data.Pages`. It is conventional to use the
   192  aliased form `.Pages`.
   193  
   194  ### `.Pages` compared to `.Site.Pages`
   195  
   196  {{< readfile file="/content/en/readfiles/pages-vs-site-pages.md" markdown="true" >}}
   197  
   198  ## Page-level Params
   199  
   200  Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.
   201  
   202  ```
   203  ---
   204  title: My First Post
   205  date: 2017-02-20T15:26:23-06:00
   206  categories: [one]
   207  tags: [two,three,four]
   208  ```
   209  
   210  With the above front matter, the `tags` and `categories` taxonomies are accessible via the following:
   211  
   212  * `.Params.tags`
   213  * `.Params.categories`
   214  
   215  {{% note "Casing of Params" %}}
   216  Page-level `.Params` are *only* accessible in lowercase.
   217  {{% /note %}}
   218  
   219  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`:
   220  
   221  ```
   222  ---
   223  ...
   224  affiliatelink: "http://www.my-book-link.here"
   225  recommendedby: "My Mother"
   226  ...
   227  ---
   228  ```
   229  
   230  These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively.
   231  
   232  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.
   233  
   234  {{< code file="/themes/yourtheme/layouts/review/single.html" >}}
   235  <h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
   236  <p>It was recommended by {{ .Params.recommendedby }}.</p>
   237  {{< /code >}}
   238  
   239  This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/):
   240  
   241  {{< output file="yourbaseurl/review/book01/index.html" >}}
   242  <h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
   243  <p>It was recommended by my Mother.</p>
   244  {{< /output >}}
   245  
   246  {{% note %}}
   247  See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content.
   248  {{% /note %}}
   249  
   250  ### The `.Param` Method
   251  
   252  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):
   253  
   254  ```
   255  {{ $.Param "header_image" }}
   256  ```
   257  
   258  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`).
   259  
   260  ### Access Nested Fields in Front Matter
   261  
   262  When front matter contains nested fields like the following:
   263  
   264  ```
   265  ---
   266  author:
   267    given_name: John
   268    family_name: Feminella
   269    display_name: John Feminella
   270  ---
   271  ```
   272  `.Param` can access these fields by concatenating the field names together with a dot:
   273  
   274  ```
   275  {{ $.Param "author.display_name" }}
   276  ```
   277  
   278  If your front matter contains a top-level key that is ambiguous with a nested key, as in the following case:
   279  
   280  ```
   281  ---
   282  favorites.flavor: vanilla
   283  favorites:
   284    flavor: chocolate
   285  ---
   286  ```
   287  
   288  The top-level key will be preferred. Therefore, the following method, when applied to the previous example, will print `vanilla` and not `chocolate`:
   289  
   290  ```
   291  {{ $.Param "favorites.flavor" }}
   292  => vanilla
   293  ```
   294  
   295  [gitinfo]: /variables/git/
   296  [File Variables]: /variables/files/