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