github.com/rabbouni145/gg@v0.47.1/docs/content/en/templates/ordering-and-grouping.md (about) 1 --- 2 title: Ordere 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](http://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 Sometimes you only want to list a subset of the available content. A common request is to only display “Posts” on the homepage. You can accomplish this with the `where` function. 340 341 ### `where` 342 343 `where` works in a similar manner to the `where` keyword in SQL. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments: 344 345 1. `array` or a `slice of maps or structs` 346 2. `key` or `field name` 347 3. `match value` 348 349 {{< code file="layouts/_default/index.html" >}} 350 {{ range where .Pages "Section" "post" }} 351 {{ .Content }} 352 {{ end }} 353 {{< /code >}} 354 355 ### `first` 356 357 `first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments: 358 359 1. `array` or `slice of maps or structs` 360 2. `number of elements` 361 362 {{< code file="layout/_default/section.html" >}} 363 {{ range first 10 .Pages }} 364 {{ .Render "summary" }} 365 {{ end }} 366 {{< /code >}} 367 368 ### `first` and `where` Together 369 370 Using `first` and `where` together can be very powerful: 371 372 {{< code file="first-and-where-together.html" >}} 373 {{ range first 5 (where .Pages "Section" "post") }} 374 {{ .Content }} 375 {{ end }} 376 {{< /code >}} 377 378 379 [views]: /templates/views/