HUGO
Menu
GitHub 90498 stars Mastodon

GroupByParamDate

Returns the given page collection grouped by the given date parameter in descending order.
Syntax
PAGES.GroupByParamDate PARAM LAYOUT [SORT]
Returns
page.PagesGroup

Usage

The layout string has the same format as the layout string for the time.Format function. The resulting group key is localized for language and region.

For the optional sort order, specify either asc for ascending order, or desc for descending order.

Use the GroupByParamDate method to group by a custom date parameter. To group by a reserved date field, use the corresponding grouping method: GroupByDate, GroupByExpiryDate, GroupByLastmod, or GroupByPublishDate.

Deprecated in v0.169.0

Passing the name of a reserved field, such as date, to the GroupByParamDate method is deprecated. Use the corresponding grouping method instead, such as GroupByDate. Hugo does not log a deprecation warning in every case.

To group content by year and month:

{{ range .Pages.GroupByParamDate "eventDate" "January 2006" }}
  <p>{{ .Key }}</p>
  <ul>
    {{ range .Pages }}
      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
    {{ end }}
  </ul>
{{ end }}

To sort the groups in ascending order:

{{ range .Pages.GroupByParamDate "eventDate" "January 2006" "asc" }}
  <p>{{ .Key }}</p>
  <ul>
    {{ range .Pages }}
      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
    {{ end }}
  </ul>
{{ end }}

The pages within each group will also be sorted by the parameter date, either ascending or descending depending on your grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title:

{{ range .Pages.GroupByParamDate "eventDate" "January 2006" }}
  <p>{{ .Key }}</p>
  <ul>
    {{ range .Pages.ByTitle }}
      <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
    {{ end }}
  </ul>
{{ end }}

Layout string

Format a time.Time value based on Go’s reference time:

Mon Jan 2 15:04:05 MST 2006

Create a layout string using these components:

DescriptionValid components
Year"2006" "06"
Month"Jan" "January" "01" "1"
Day of the week"Mon" "Monday"
Day of the month"2" "_2" "02"
Day of the year"__2" "002"
Hour"15" "3" "03"
Minute"4" "04"
Second"5" "05"
AM/PM mark"PM"
Time zone abbreviation"MST"
Time zone offsets"-0700" "-07:00" "-07" "-070000" "-07:00:00"

Replace the sign in the layout string with a Z to print Z instead of the offset when the offset is zero.

DescriptionValid components
Time zone offsets"Z0700" "Z07:00" "Z07" "Z070000" "Z07:00:00"
{{ $t := "2023-01-27T23:44:58-08:00" }}
{{ $t = time.AsTime $t }}
{{ $t = $t.Format "Jan 02, 2006 3:04 PM Z07:00" }}

{{ $t }} → Jan 27, 2023 11:44 PM -08:00

The MST component prints the abbreviation of the date/time’s time zone, such as PST or CET. If the date/time has a time zone offset but no time zone, the component prints the offset instead, such as -0800. Whether a date/time created from a string with an offset has a time zone can depend on the time zone of the system running Hugo.