ordering-and-grouping.md (8732B)
1 ---
2 title: Ordering and Grouping Hugo Lists
3 linktitle: List Ordering and Grouping
4 description: You can group or order your content in both your templating and content front matter.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-02-01
8 categories: [templates]
9 keywords: []
10 menu:
11 docs:
12 parent: "templates"
13 weight: 27
14 weight: 27
15 sections_weight: 27
16 draft: true
17 aliases: [/templates/ordering/,/templates/grouping/]
18 toc: true
19 notes: This was originally going to be a separate page on the new docs site but it now makes more sense to keep everything within the templates/lists page. - rdwatters, 2017-03-12.
20 ---
21
22 In Hugo, a list template is any template that will be used to render multiple pieces of content in a single HTML page.
23
24 ## Example List Templates
25
26 ### Section Template
27
28 This list template is used for [spf13.com](https://spf13.com/). It makes use of [partial templates][partials]. All examples use a [view](/templates/views/) called either "li" or "summary."
29
30 {{< code file="layouts/section/post.html" >}}
31 {{ partial "header.html" . }}
32 {{ partial "subheader.html" . }}
33
34 <section id="main">
35 <div>
36 <h1 id="title">{{ .Title }}</h1>
37 <ul id="list">
38 {{ range .Pages }}
39 {{ .Render "li"}}
40 {{ end }}
41 </ul>
42 </div>
43 </section>
44 {{ partial "footer.html" . }}
45 {{< /code >}}
46
47 ### Taxonomy Template
48
49 {{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}}
50 {{ define "main" }}
51 <section id="main">
52 <div>
53 <h1 id="title">{{ .Title }}</h1>
54 {{ range .Pages }}
55 {{ .Render "summary"}}
56 {{ end }}
57 </div>
58 </section>
59 {{ end }}
60 {{< /code >}}
61
62 ## Order Content
63
64 Hugo lists render the content based on metadata provided in the [front matter](/content-management/front-matter/)..
65
66 Here are a variety of different ways you can order the content items in
67 your list templates:
68
69 ### Default: Weight > Date
70
71 {{< code file="layouts/partials/order-default.html" >}}
72 <ul class="pages">
73 {{ range .Pages }}
74 <li>
75 <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
76 <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
77 </li>
78 {{ end }}
79 </ul>
80 {{< /code >}}
81
82 ### By Weight
83
84 {{< code file="layouts/partials/by-weight.html" >}}
85 {{ range .Pages.ByWeight }}
86 <li>
87 <a href="{{ .Permalink }}">{{ .Title }}</a>
88 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
89 </li>
90 {{ end }}
91 {{< /code >}}
92
93 ### By Date
94
95 {{< code file="layouts/partials/by-date.html" >}}
96 {{ range .Pages.ByDate }}
97 <li>
98 <a href="{{ .Permalink }}">{{ .Title }}</a>
99 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
100 </li>
101 {{ end }}
102 {{< /code >}}
103
104 ### By Publish Date
105
106 {{< code file="layouts/partials/by-publish-date.html" >}}
107 {{ range .Pages.ByPublishDate }}
108 <li>
109 <a href="{{ .Permalink }}">{{ .Title }}</a>
110 <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
111 </li>
112 {{ end }}
113 {{< /code >}}
114
115 ### By Expiration Date
116
117 {{< code file="layouts/partials/by-expiry-date.html" >}}
118 {{ range .Pages.ByExpiryDate }}
119 <li>
120 <a href="{{ .Permalink }}">{{ .Title }}</a>
121 <div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
122 </li>
123 {{ end }}
124 {{< /code >}}
125
126 ### By Last Modified Date
127
128 {{< code file="layouts/partials/by-last-mod.html" >}}
129 {{ range .Pages.ByLastmod }}
130 <li>
131 <a href="{{ .Permalink }}">{{ .Title }}</a>
132 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
133 </li>
134 {{ end }}
135 {{< /code >}}
136
137 ### By Length
138
139 {{< code file="layouts/partials/by-length.html" >}}
140 {{ range .Pages.ByLength }}
141 <li>
142 <a href="{{ .Permalink }}">{{ .Title }}</a>
143 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
144 </li>
145 {{ end }}
146 {{< /code >}}
147
148
149 ### By Title
150
151 {{< code file="layouts/partials/by-title.html" >}}
152 {{ range .Pages.ByTitle }}
153 <li>
154 <a href="{{ .Permalink }}">{{ .Title }}</a>
155 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
156 </li>
157 {{ end }}
158 {{< /code >}}
159
160 ### By Link Title
161
162 {{< code file="layouts/partials/by-link-title.html" >}}
163 {{ range .Pages.ByLinkTitle }}
164 <li>
165 <a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
166 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
167 </li>
168 {{ end }}
169 {{< /code >}}
170
171 ### By Parameter
172
173 Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering.
174
175 The below example sorts a list of posts by their rating.
176
177 {{< code file="layouts/partials/by-rating.html" >}}
178 {{ range (.Pages.ByParam "rating") }}
179 <!-- ... -->
180 {{ end }}
181 {{< /code >}}
182
183 If the front matter field of interest is nested beneath another field, you can
184 also get it:
185
186 {{< code file="layouts/partials/by-nested-param.html" >}}
187 {{ range (.Pages.ByParam "author.last_name") }}
188 <!-- ... -->
189 {{ end }}
190 {{< /code >}}
191
192 ### Reverse Order
193
194 Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example:
195
196 {{< code file="layouts/partials/by-date-reverse.html" >}}
197 {{ range .Pages.ByDate.Reverse }}
198 <li>
199 <a href="{{ .Permalink }}">{{ .Title }}</a>
200 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
201 </li>
202 {{ end }}
203 {{< /code >}}
204
205 ## Group Content
206
207 Hugo provides some functions for grouping pages by Section, Type, Date, etc.
208
209 ### By Page Field
210
211 {{< code file="layouts/partials/by-page-field.html" >}}
212 {{ range .Pages.GroupBy "Section" }}
213 <h3>{{ .Key }}</h3>
214 <ul>
215 {{ range .Pages }}
216 <li>
217 <a href="{{ .Permalink }}">{{ .Title }}</a>
218 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
219 </li>
220 {{ end }}
221 </ul>
222 {{ end }}
223 {{< /code >}}
224
225 ### By Page date
226
227 {{< code file="layouts/partials/by-page-date.html" >}}
228 {{ range .Pages.GroupByDate "2006-01" }}
229 <h3>{{ .Key }}</h3>
230 <ul>
231 {{ range .Pages }}
232 <li>
233 <a href="{{ .Permalink }}">{{ .Title }}</a>
234 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
235 </li>
236 {{ end }}
237 </ul>
238 {{ end }}
239 {{< /code >}}
240
241 ### By Page publish date
242
243 {{< code file="layouts/partials/by-page-publish-date.html" >}}
244 {{ range .Pages.GroupByPublishDate "2006-01" }}
245 <h3>{{ .Key }}</h3>
246 <ul>
247 {{ range .Pages }}
248 <li>
249 <a href="{{ .Permalink }}">{{ .Title }}</a>
250 <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
251 </li>
252 {{ end }}
253 </ul>
254 {{ end }}
255 {{< /code >}}
256
257 ### By Page Param
258
259 {{< code file="layouts/partials/by-page-param.html" >}}
260 {{ range .Pages.GroupByParam "param_key" }}
261 <h3>{{ .Key }}</h3>
262 <ul>
263 {{ range .Pages }}
264 <li>
265 <a href="{{ .Permalink }}">{{ .Title }}</a>
266 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
267 </li>
268 {{ end }}
269 </ul>
270 {{ end }}
271 {{< /code >}}
272
273 ### By Page Param in Date Format
274
275 {{< code file="layouts/partials/by-page-param-as-date.html" >}}
276 {{ range .Pages.GroupByParamDate "param_key" "2006-01" }}
277 <h3>{{ .Key }}</h3>
278 <ul>
279 {{ range .Pages }}
280 <li>
281 <a href="{{ .Permalink }}">{{ .Title }}</a>
282 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
283 </li>
284 {{ end }}
285 </ul>
286 {{ end }}
287 {{< /code >}}
288
289 ### Reverse Key Order
290
291 The ordering of the groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (newest first) for dates.
292
293 While these are logical defaults, they are not always the desired order. There are two different syntaxes to change the order, both of which work the same way. You can use your preferred syntax.
294
295 #### Reverse Method
296
297 ```
298 {{ range (.Pages.GroupBy "Section").Reverse }}
299 ```
300
301 ```
302 {{ range (.Pages.GroupByDate "2006-01").Reverse }}
303 ```
304
305
306 #### Provide the Alternate Direction
307
308 ```
309 {{ range .Pages.GroupByDate "2006-01" "asc" }}
310 ```
311
312 ```
313 {{ range .Pages.GroupBy "Section" "desc" }}
314 ```
315
316 ### Order Within Groups
317
318 Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available.
319
320 In the following example, groups are ordered chronologically and then content
321 within each group is ordered alphabetically by title.
322
323 {{< code file="layouts/partials/by-group-by-page.html" >}}
324 {{ range .Pages.GroupByDate "2006-01" "asc" }}
325 <h3>{{ .Key }}</h3>
326 <ul>
327 {{ range .Pages.ByTitle }}
328 <li>
329 <a href="{{ .Permalink }}">{{ .Title }}</a>
330 <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
331 </li>
332 {{ end }}
333 </ul>
334 {{ end }}
335 {{< /code >}}
336
337 ## Filter and Limiting Lists
338
339 See the [_Lists/Filtering and Limiting Lists_
340 section][filteringandlimitinglists] for details.
341
342
343 [views]: /templates/views/
344 [filteringandlimitinglists]: /templates/lists/#filtering-and-limiting-lists