github.com/rabbouni145/gg@v0.47.1/docs/content/en/functions/format.md (about)

     1  ---
     2  title: .Format
     3  description: Formats built-in Hugo dates---`.Date`, `.PublishDate`, and `.Lastmod`---according to Go's layout string.
     4  godocref: https://golang.org/pkg/time/#example_Time_Format
     5  date: 2017-02-01
     6  publishdate: 2017-02-01
     7  lastmod: 2017-02-01
     8  categories: [functions]
     9  menu:
    10    docs:
    11      parent: "functions"
    12  keywords: [dates,time]
    13  signature: [".Format FORMAT"]
    14  workson: [times]
    15  hugoversion:
    16  relatedfuncs: [dateFormat,now,Unix,time]
    17  deprecated: false
    18  aliases: []
    19  toc: true
    20  ---
    21  
    22  `.Format` will format date values defined in your front matter and can be used as a property on the following [page variables][pagevars]:
    23  
    24  * `.PublishDate`
    25  * `.Date`
    26  * `.Lastmod`
    27  
    28  Assuming a key-value of `date: 2017-03-03` in a content file's front matter, your can run the date through `.Format` followed by a layout string for your desired output at build time:
    29  
    30  ```
    31  {{ .PublishDate.Format "January 2, 2006" }} => March 3, 2017
    32  ```
    33  
    34  For formatting *any* string representations of dates defined in your front matter, see the [`dateFormat` function][dateFormat], which will still leverage the Go layout string explained below but uses a slightly different syntax.
    35  
    36  ## Go's Layout String
    37  
    38  Hugo templates [format your dates][time] via layout strings that point to a specific reference time:
    39  
    40  ```
    41  Mon Jan 2 15:04:05 MST 2006
    42  ```
    43  
    44  While this may seem arbitrary, the numerical value of `MST` is `07`, thus making the layout string a sequence of numbers.
    45  
    46  Here is a visual explanation [taken directly from the Go docs][gdex]:
    47  
    48  ```
    49   Jan 2 15:04:05 2006 MST
    50  => 1 2  3  4  5    6  -7
    51  ```
    52  
    53  ### Hugo Date and Time Templating Reference
    54  
    55  The following examples show the layout string followed by the rendered output.
    56  
    57  The examples were rendered and tested in [CST][] and all point to the same field in a content file's front matter:
    58  
    59  ```
    60  date: 2017-03-03T14:15:59-06:00
    61  ```
    62  
    63  `.Date` (i.e. called via [page variable][pagevars])
    64  : **Returns**: `2017-03-03 14:15:59 -0600 CST`
    65  
    66  `"Monday, January 2, 2006"`
    67  : **Returns**: `Friday, March 3, 2017`
    68  
    69  `"Mon Jan 2 2006"`
    70  : **Returns**: `Fri Mar 3 2017`
    71  
    72  `"January 2006"`
    73  : **Returns**: `March 2017`
    74  
    75  `"2006-01-02"`
    76  : **Returns**: `2017-03-03`
    77  
    78  `"Monday"`
    79  : **Returns**: `Friday`
    80  
    81  `"02 Jan 06 15:04 MST"` (RFC822)
    82  : **Returns**: `03 Mar 17 14:15 CST`
    83  
    84  `"02 Jan 06 15:04 -0700"` (RFC822Z)
    85  : **Returns**: `03 Mar 17 14:15 -0600`
    86  
    87  `"Mon, 02 Jan 2006 15:04:05 MST"` (RFC1123)
    88  : **Returns**: `Fri, 03 Mar 2017 14:15:59 CST`
    89  
    90  `"Mon, 02 Jan 2006 15:04:05 -0700"` (RFC339)
    91  : **Returns**: `Fri, 03 Mar 2017 14:15:59 -0600`
    92  
    93  ### Cardinal Numbers and Ordinal Abbreviations
    94  
    95  Spelled-out cardinal numbers (e.g. "one", "two", and "three") and ordinal abbreviations (i.e., with shorted suffixes like "1st", "2nd", and "3rd") are not currently supported:
    96  
    97  ```
    98  {{.Date.Format "Jan 2nd 2006"}}
    99  ```
   100  
   101  Hugo assumes you want to append `nd` as a string to the day of the month and outputs the following:
   102  
   103  ```
   104  Mar 3nd 2017
   105  ```
   106  
   107  <!-- Content idea: see https://discourse.gohugo.io/t/formatting-a-date-with-suffix-2nd/5701 -->
   108  
   109  ### Use `.Local` and `.UTC`
   110  
   111  In conjunction with the [`dateFormat` function][dateFormat], you can also convert your dates to `UTC` or to local timezones:
   112  
   113  `{{ dateFormat "02 Jan 06 15:04 MST" .Date.UTC }}`
   114  : **Returns**: `03 Mar 17 20:15 UTC`
   115  
   116  `{{ dateFormat "02 Jan 06 15:04 MST" .Date.Local }}`
   117  : **Returns**: `03 Mar 17 14:15 CST`
   118  
   119  [CST]: https://en.wikipedia.org/wiki/Central_Time_Zone
   120  [dateFormat]: /functions/dateformat/
   121  [gdex]: https://golang.org/pkg/time/#example_Time_Format
   122  [pagevars]: /variables/page/
   123  [time]: https://golang.org/pkg/time/