mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
ba45da9d03
32356e4e Fix typo in header of shortcode-templates.md c8f1a2d2 Correct code example for index template function bfa6a55d Escape code fencing ff8b2f99 Fix typos in deployment with wercker tutorial 557c36e8 theme: Merge commit '7fbb4bed25001182bfeb91f79db0f0c1936582ee' 7fbb4bed Squashed 'themes/gohugoioTheme/' changes from 7dd8a302..ca53082d ce31cee0 Add "See Also" config 158cee1b Make the tags into keywords 61600be6 Add a note to the related section 49edb5a2 Relase 0.27.1 c9bbc001 releaser: Add release notes to /docs for release of 0.27.1 213c6c3b Add bugs poster 8b4590cd Add KeyCDN integration tutorial 2b277859 Add tutorial videos to several docs pages 950fef1f Update roadmap to link to the correct milestones page 496f5bf6 Rename relnotes d6f9378d Bump Netlify versions to 0.27 087fde7f Update 0.27 release notes 603f94ae docs: Document Related Content 3790f6a3 releaser: Bump versions for release of 0.27 0948868c releaser: Add release notes to /docs for release of 0.27 git-subtree-dir: docs git-subtree-split: 32356e4eabe357ae914f4d1d59e8ae31ce936723
126 lines
3.5 KiB
Markdown
126 lines
3.5 KiB
Markdown
---
|
|
title: .Format
|
|
description: Formats built-in Hugo dates---`.Date`, `.PublishDate`, and `.LastMod`---according to Go's layout string.
|
|
godocref: https://golang.org/pkg/time/#example_Time_Format
|
|
date: 2017-02-01
|
|
publishdate: 2017-02-01
|
|
lastmod: 2017-02-01
|
|
categories: [functions]
|
|
menu:
|
|
docs:
|
|
parent: "functions"
|
|
keywords: [dates,time]
|
|
signature: [".Format FORMAT"]
|
|
workson: [times]
|
|
hugoversion:
|
|
relatedfuncs: [dateFormat,now,Unix,time]
|
|
deprecated: false
|
|
aliases: []
|
|
toc: true
|
|
---
|
|
|
|
`.Format` will format date values defined in your front matter and can be used as a property on the following [page variables][pagevars]:
|
|
|
|
* `.PublishDate`
|
|
* `.Date`
|
|
* `.LastMod`
|
|
|
|
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:
|
|
|
|
```
|
|
{{ .PublishDate.Format "January 2, 2006" }} => March 3, 2017
|
|
```
|
|
|
|
For formatting *any* string representations of dates defined in your front matter, see the [`dateFormat` function][dateFormat], which will still leverage the Golang layout string explained below but uses a slightly different syntax.
|
|
|
|
## Go's Layout String
|
|
|
|
Hugo templates [format your dates][time] via layout strings that point to a specific reference time:
|
|
|
|
```
|
|
Mon Jan 2 15:04:05 MST 2006
|
|
```
|
|
|
|
While this may seem arbitrary, the numerical value of `MST` is `07`, thus making the layout string a sequence of numbers.
|
|
|
|
Here is a visual explanation [taken directly from the Go docs][gdex]:
|
|
|
|
```
|
|
Jan 2 15:04:05 2006 MST
|
|
=> 1 2 3 4 5 6 -7
|
|
```
|
|
|
|
### Hugo Date and Time Templating Reference
|
|
|
|
The following examples show the layout string followed by the rendered output.
|
|
|
|
The examples were rendered and tested in [CST][] and all point to the same field in a content file's front matter:
|
|
|
|
```
|
|
date: 2017-03-03T14:15:59-06:00
|
|
```
|
|
|
|
`.Date` (i.e. called via [page variable][pagevars])
|
|
: **Returns**: `2017-03-03 14:15:59 -0600 CST`
|
|
|
|
`"Monday, January 2, 2006"`
|
|
: **Returns**: `Friday, March 3, 2017`
|
|
|
|
`"Mon Jan 2 2006"`
|
|
: **Returns**: `Fri Mar 3 2017`
|
|
|
|
`"January 2nd"`
|
|
: **Returns**: `March 3rd`
|
|
|
|
`"January 2006"`
|
|
: **Returns**: `March 2017`
|
|
|
|
`"2006-01-02"`
|
|
: **Returns**: `2017-03-03`
|
|
|
|
`"Monday"`
|
|
: **Returns**: `Friday`
|
|
|
|
`"02 Jan 06 15:04 MST"` (RFC822)
|
|
: **Returns**: `03 Mar 17 14:15 CST`
|
|
|
|
`"02 Jan 06 15:04 -0700"` (RFC822Z)
|
|
: **Returns**: `03 Mar 17 14:15 -0600`
|
|
|
|
`"Mon, 02 Jan 2006 15:04:05 MST"` (RFC1123)
|
|
: **Returns**: `Fri, 03 Mar 2017 14:15:59 CST`
|
|
|
|
`"Mon, 02 Jan 2006 15:04:05 -0700"` (RFC339)
|
|
: **Returns**: `Fri, 03 Mar 2017 14:15:59 -0600`
|
|
|
|
### Cardinal Numbers and Ordinal Abbreviations
|
|
|
|
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:
|
|
|
|
```
|
|
{{.Date.Format "Jan 2nd 2006"}}
|
|
```
|
|
|
|
Hugo assumes you want to append `nd` as a string to the day of the month and outputs the following:
|
|
|
|
```
|
|
Mar 3nd 2017
|
|
```
|
|
|
|
<!-- Content idea: see https://discourse.gohugo.io/t/formatting-a-date-with-suffix-2nd/5701 -->
|
|
|
|
### Use `.Local` and `.UTC`
|
|
|
|
In conjunction with the [`dateFormat` function][dateFormat], you can also convert your dates to `UTC` or to local timezones:
|
|
|
|
`{{ dateFormat "02 Jan 06 15:04 MST" .Date.UTC }}`
|
|
: **Returns**: `03 Mar 17 20:15 UTC`
|
|
|
|
`{{ dateFormat "02 Jan 06 15:04 MST" .Date.Local }}`
|
|
: **Returns**: `03 Mar 17 14:15 CST`
|
|
|
|
[CST]: https://en.wikipedia.org/wiki/Central_Time_Zone
|
|
[dateFormat]: /functions/dateformat/
|
|
[gdex]: https://golang.org/pkg/time/#example_Time_Format
|
|
[pagevars]: /variables/page/
|
|
[time]: https://golang.org/pkg/time/
|