Merge commit 'e509cac533600cf4fa8382c9cdab78ddd82db688'

docs/content/en/functions/time/AsTime.md

@@ -0,0 +1,64 @@
+---
+title: time.AsTime
+linkTitle: time
+description: Converts a timestamp string into a `time.Time` structure.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [time]
+  returnType: time.Time
+  signatures: ['time.AsTime INPUT [TIMEZONE]']
+relatedFunctions:
+  - time.AsTime
+  - time.Duration
+  - time.Format
+  - time.Now
+  - time.ParseDuration
+aliases: [/functions/time]
+---
+
+
+`time` converts a timestamp string with an optional default location into a [`time.Time`](https://godoc.org/time#Time) structure so you can access its fields:
+
+```go-html-template
+{{ time "2016-05-28" }} → "2016-05-28T00:00:00Z"
+{{ (time "2016-05-28").YearDay }} → 149
+{{ mul 1000 (time "2016-05-28T10:30:00.00+10:00").Unix }} → 1464395400000, or Unix time in milliseconds
+```
+
+## Using locations
+
+The optional `TIMEZONE` argument is a string that sets a default time zone (or more specific, the location, which represents the collection of time offsets in a geographical area) that is associated with the specified time value. If the time value has an explicit timezone or offset specified, it will take precedence over the `TIMEZONE` argument.
+
+The list of valid locations may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+If no `TIMEZONE` is set, the `timeZone` from site configuration will be used.
+
+```go-html-template
+{{ time "2020-10-20" }} → 2020-10-20 00:00:00 +0000 UTC
+{{ time "2020-10-20" "America/Los_Angeles" }} → 2020-10-20 00:00:00 -0700 PDT
+{{ time "2020-01-20" "America/Los_Angeles" }} → 2020-01-20 00:00:00 -0800 PST
+```
+
+## Example: Using `time` to get month index
+
+The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"` in a content's front matter---converts the timestamp (string) to an integer using the [`int` function][int], and then uses [`printf`] to convert the `Month` property of `time` into an index.
+
+The following example may be useful when setting up [multilingual sites][multilingual]:
+
+{{< code file="unix-to-month-integer.html" >}}
+{{ $time := time (int .Params.addDate)}}
+=> $time = 1489276800
+{{ $time.Month }}
+=> "March"
+{{ $monthindex := printf "%d" $time.Month }}
+=> $monthindex = 3
+{{< /code >}}
+
+
+[int]: /functions/cast/toint
+[multilingual]: /content-management/multilingual/
+[`printf`]: /functions/fmt/printf

docs/content/en/functions/time/Duration.md

@@ -0,0 +1,46 @@
+---
+title: time.Duration
+linkTitle: duration
+description: Returns a `time.Duration` structure, using the given time unit and duration number.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [duration]
+  returnType: time.Duration
+  signatures: [time.Duration TIME_UNIT DURATION_NUMBER]
+relatedFunctions:
+  - time.AsTime
+  - time.Duration
+  - time.Format
+  - time.Now
+  - time.ParseDuration
+aliases: [/functions/duration]
+---
+
+`time.Duration` converts a given number into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields. E.g. you can perform [time operations](https://pkg.go.dev/time#Duration) on the returned `time.Duration` value:
+
+```go-html-template
+{{ printf "There are %.0f seconds in one day." (duration "hour" 24).Seconds }}
+<!-- Output: There are 86400 seconds in one day. -->
+```
+
+Make your code simpler to understand by using a [chained pipeline](https://pkg.go.dev/text/template#hdr-Pipelines):
+
+```go-html-template
+{{ mul 7.75 60 | duration "minute" }} → 7h45m0s
+{{ mul 120 60 | mul 1000 | duration "millisecond" }} → 2h0m0s
+```
+
+You have to specify a time unit for the number given to the function. Valid time units are:
+
+Duration|Valid time units
+:--|:--
+hours|`hour`, `h`
+minutes|`minute`, `m`
+seconds|`second`, `s`
+milliseconds|`millisecond`, `ms`
+microseconds|`microsecond`, `us`, `µs`
+nanoseconds|`nanosecond`, `ns`

docs/content/en/functions/time/Format.md

@@ -0,0 +1,76 @@
+---
+title: time.Format
+description: Returns a formatted and localized time.Time value.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [dateFormat]
+  returnType: string
+  signatures: [time.Format LAYOUT INPUT]
+relatedFunctions:
+  - time.AsTime
+  - time.Duration
+  - time.Format
+  - time.Now
+  - time.ParseDuration
+aliases: [/functions/dateformat]
+toc: true
+---
+
+```go-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $format := "2 Jan 2006" }}
+
+{{ $t | time.Format $format }} → 27 Jan 2023
+
+{{ $t = time.AsTime $t }}
+{{ $t | time.Format $format }} → 27 Jan 2023
+```
+
+## Layout string
+
+{{% readfile file="/functions/_common/time-layout-string.md" %}}
+
+## Localization
+
+Use the `time.Format` function to localize `time.Time` values for the current language and region.
+
+{{% note %}}
+{{% readfile file="/functions/_common/locales.md" %}}
+{{% /note %}}
+
+
+Use the layout string as described above, or one of the tokens below. For example:
+
+```go-template
+{{ .Date | time.Format ":date_medium" }} → Jan 27, 2023
+```
+
+Localized to en-US:
+
+Token|Result
+:--|:--
+`:date_full`|`Friday, January 27, 2023`
+`:date_long`|`January 27, 2023`
+`:date_medium`|`Jan 27, 2023`
+`:date_short`|`1/27/23`
+`:time_full`|`11:44:58 pm Pacific Standard Time`
+`:time_long`|`11:44:58 pm PST`
+`:time_medium`|`11:44:58 pm`
+`:time_short`|`11:44 pm`
+
+Localized to de-DE:
+
+Token|Result
+:--|:--
+`:date_full`|`Freitag, 27. Januar 2023`
+`:date_long`|`27. Januar 2023`
+`:date_medium`|`27.01.2023`
+`:date_short`|`27.01.23`
+`:time_full`|`23:44:58 Nordamerikanische Westküsten-Normalzeit`
+`:time_long`|`23:44:58 PST`
+`:time_medium`|`23:44:58`
+`:time_short`|`23:44`

docs/content/en/functions/time/Now.md

@@ -0,0 +1,51 @@
+---
+title: time.Now
+linkTitle: now
+description: Returns the current local time 
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: [now]
+  returnType: time.Time
+  signatures: [time.Now]
+relatedFunctions:
+  - time.AsTime
+  - time.Duration
+  - time.Format
+  - time.Now
+  - time.ParseDuration
+aliases: [/functions/now]
+---
+
+See [`time.Time`](https://godoc.org/time#Time).
+
+For example, building your site on June 24, 2017, with the following templating:
+
+```go-html-template
+<div>
+    <small>&copy; {{ now.Format "2006" }}</small>
+</div>
+```
+
+would produce the following:
+
+```html
+<div>
+    <small>&copy; 2017</small>
+</div>
+```
+
+The above example uses the [`.Format` function](/functions/format), which page includes a full listing of date formatting using Go's layout string.
+
+{{% note %}}
+Older Hugo themes may still be using the obsolete Page’s `.Now` (uppercase with leading dot), which causes build error that looks like the following:
+
+    ERROR ... Error while rendering "..." in "...": ...
+    executing "..." at <.Now.Format>:
+    can't evaluate field Now in type *hugolib.PageOutput
+
+Be sure to use `now` (lowercase with _**no**_ leading dot) in your templating.
+{{% /note %}}

docs/content/en/functions/time/ParseDuration.md

@@ -0,0 +1,30 @@
+---
+title: time.ParseDuration
+description: Parses a given duration string into a `time.Duration` structure.
+categories: [functions]
+keywords: []
+menu:
+  docs:
+    parent: functions
+function:
+  aliases: []
+  returnType: time.Duration
+  signatures: [time.ParseDuration DURATION]
+relatedFunctions:
+  - time.AsTime
+  - time.Duration
+  - time.Format
+  - time.Now
+  - time.ParseDuration
+aliases: [/functions/time.parseduration]
+---
+
+`time.ParseDuration` parses a duration string into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields.
+A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
+
+You can perform [time operations](https://pkg.go.dev/time#Duration) on the returned `time.Duration` value:
+
+```go-html-template
+{{ printf "There are %.0f seconds in one day." (time.ParseDuration "24h").Seconds }}
+<!-- Output: There are 86400 seconds in one day. -->
+```