diff options
Diffstat (limited to 'docs/content/en/templates')
| -rw-r--r-- | docs/content/en/templates/404.md | 1 | ||||
| -rw-r--r-- | docs/content/en/templates/files.md | 6 | ||||
| -rw-r--r-- | docs/content/en/templates/introduction.md | 361 | ||||
| -rw-r--r-- | docs/content/en/templates/taxonomy-templates.md | 171 |
4 files changed, 341 insertions, 198 deletions
diff --git a/docs/content/en/templates/404.md b/docs/content/en/templates/404.md index eba2d95df..c6bea1912 100644 --- a/docs/content/en/templates/404.md +++ b/docs/content/en/templates/404.md @@ -50,6 +50,7 @@ Your 404.html file can be set to load automatically when a visitor enters a mist * Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site. * Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. * Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI. +* Amazon CloudFont. You can specify the page in the Error Pages section in the CloudFont Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html) * Caddy Server. Using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors) {{% note %}} diff --git a/docs/content/en/templates/files.md b/docs/content/en/templates/files.md index 6e6f3ec4e..4969a4f33 100644 --- a/docs/content/en/templates/files.md +++ b/docs/content/en/templates/files.md @@ -104,12 +104,12 @@ And here is the result as [called directly in the Hugo docs][] and rendered for {{< readfile file="/content/en/readfiles/testing.txt" markdown="true">}} -[called directly in the Hugo docs]: https://github.com/gohugoio/hugo/blob/master/docs/content/templates/files.md +[called directly in the Hugo docs]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/templates/files.md [dirindex]: https://github.com/gohugoio/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html [osfileinfo]: https://golang.org/pkg/os/#FileInfo [readDir]: /functions/readdir/ [readFile]: /functions/readfile/ [sc]: /content-management/shortcodes/ [sct]: /templates/shortcode-templates/ -[readfilesource]: https://github.com/gohugoio/hugo/blob/master/ -[testfile]: https://github.com/gohugoio/hugo/blob/master/docs/testfile +[readfilesource]: https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/readfile.html +[testfile]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/readfiles/testing.txt diff --git a/docs/content/en/templates/introduction.md b/docs/content/en/templates/introduction.md index 0b9ad051b..1e1778eb0 100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@ -20,26 +20,39 @@ toc: true --- {{% note %}} -The following is only a primer on Go templates. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/). +The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](http://golang.org/pkg/html/template/). {{% /note %}} -Go templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. +Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. {{< youtube gnJbPO-GFIw >}} ## Basic Syntax -Go templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go template variables and functions are accessible within `{{ }}`. +Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`. ### Access a Predefined Variable -``` -{{ foo }} +A _predefined variable_ could be a variable already existing in the +current scope (like the `.Title` example in the [Variables]({{< relref +"#variables" >}}) section below) or a custom variable (like the +`$address` example in that same section). + + +```go-html-template +{{ .Title }} +{{ $address }} ``` -Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`: +Parameters for functions are separated using spaces. The general syntax is: ``` +{{ FUNCTION ARG1 ARG2 .. }} +``` + +The following example calls the `add` function with inputs of `1` and `2`: + +```go-html-template {{ add 1 2 }} ``` @@ -47,64 +60,88 @@ Parameters for functions are separated using spaces. The following example calls Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. -``` +```go-html-template {{ .Params.bar }} ``` #### Parentheses Can be Used to Group Items Together -``` +```go-html-template {{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} ``` -## Variables +## Variables {#variables} -Each Go template gets a data object. In Hugo, each template is passed a `Page`. See [variables][] for more information. +Each Go Template gets a data object. In Hugo, each template is passed +a `Page`. In the below example, `.Title` is one of the elements +accessible in that [`Page` variable][pagevars]. -This is how you access a `Page` variable from a template: +With the `Page` being the default scope of a template, the `Title` +element in current scope (`.` -- "the **dot**") is accessible simply +by the dot-prefix (`.Title`): -``` +```go-html-template <title>{{ .Title }}</title> ``` Values can also be stored in custom variables and referenced later: -``` -{{ $address := "123 Main St."}} +{{% note %}} +The custom variables need to be prefixed with `$`. +{{% /note %}} + +```go-html-template +{{ $address := "123 Main St." }} {{ $address }} ``` {{% warning %}} -Variables defined inside `if` conditionals and similar are not visible on the outside. See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). +For Hugo v0.47 and older versions, variables defined inside `if` +conditionals and similar are not visible on the outside. +See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). Hugo has created a workaround for this issue in [Scratch](/functions/scratch). - {{% /warning %}} +For **Hugo v0.48** and newer, variables can be re-defined using the +new `=` operator (new in Go 1.11). + +Below example will work only in these newer Hugo versions. The example +prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on +all other pages: + +```go-html-template +{{ $var := "Hugo Page" }} +{{ if .IsHome }} + {{ $var = "Hugo Home" }} +{{ end }} +Var is {{ $var }} +``` + ## Functions -Go templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. +Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. [Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. ### Example 1: Adding Numbers -``` +```go-html-template {{ add 1 2 }} -=> 3 +<!-- prints 3 --> ``` ### Example 2: Comparing Numbers -``` +```go-html-template {{ lt 1 2 }} -=> true (i.e., since 1 is less than 2) +<!-- prints true (i.e., since 1 is less than 2) --> ``` -Note that both examples make use of Go template's [math functions][]. +Note that both examples make use of Go Template's [math functions][]. {{% note "Additional Boolean Operators" %}} -There are more boolean operators than those listed in the Hugo docs in the [Go template documentation](http://golang.org/pkg/text/template/#hdr-Functions). +There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](http://golang.org/pkg/text/template/#hdr-Functions). {{% /note %}} ## Includes @@ -124,116 +161,174 @@ within Hugo. The [`partial`][partials] function is used to include *partial* templates using the syntax `{{ partial "<PATH>/<PARTIAL>.<EXTENSION>" . }}`. -Example: +Example of including a `layouts/partials/header.html` partial: -``` +```go-html-template {{ partial "header.html" . }} ``` ### Template -The `template` function was used to include *partial* templates in much older -Hugo versions. Now it is still useful for calling [*internal* -templates][internal_templates]: +The `template` function was used to include *partial* templates +in much older Hugo versions. Now it useful only for calling +[*internal* templates][internal_templates]. The syntax is `{{ template +"_internal/<TEMPLATE>.<EXTENSION>" . }}`. -``` +{{% note %}} +The available **internal** templates can be found +[here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates). +{{% /note %}} + +Example of including the internal `opengraph.html` template: + +```go-html-template {{ template "_internal/opengraph.html" . }} ``` ## Logic -Go templates provide the most basic iteration and conditional logic. +Go Templates provide the most basic iteration and conditional logic. ### Iteration -Just like in Go, the Go templates make heavy use of `range` to iterate over -a map, array, or slice. The following are different examples of how to use -range. +The Go Templates make heavy use of `range` to iterate over a _map_, +_array_, or _slice_. The following are different examples of how to +use `range`. -#### Example 1: Using Context +#### Example 1: Using Context (`.`) -``` -{{ range array }} - {{ . }} +```go-html-template +{{ range $array }} + {{ . }} <!-- The . represents an element in $array --> {{ end }} ``` -#### Example 2: Declaring Value => Variable name +#### Example 2: Declaring a variable name for an array element's value -``` -{{range $element := array}} - {{ $element }} +```go-html-template +{{ range $elem_val := $array }} + {{ $elem_val }} {{ end }} ``` -#### Example 3: Declaring Key-Value Variable Name +#### Example 3: Declaring variable names for an array element's index _and_ value + +For an array or slice, the first declared variable will map to each +element's index. +```go-html-template +{{ range $elem_index, $elem_val := $array }} + {{ $elem_index }} -- {{ $elem_val }} +{{ end }} ``` -{{range $index, $element := array}} - {{ $index }} - {{ $element }} + +#### Example 4: Declaring variable names for a map element's key _and_ value + +For a map, the first declared variable will map to each map element's +key. + +```go-html-template +{{ range $elem_key, $elem_val := $map }} + {{ $elem_key }} -- {{ $elem_val }} {{ end }} ``` ### Conditionals -`if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{end}}`. +`if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{ end }}`. -Go Templates treat the following values as false: +Go Templates treat the following values as **false**: -* false -* 0 -* any zero-length array, slice, map, or string +- `false` (boolean) +- 0 (integer) +- any zero-length array, slice, map, or string -#### Example 1: `if` +#### Example 1: `with` -``` -{{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }} -``` +It is common to write "if something exists, do this" kind of +statements using `with`. -#### Example 2: `if` … `else` +{{% note %}} +`with` rebinds the context `.` within its scope (just like in `range`). +{{% /note %}} -``` -{{ if isset .Params "alt" }} - {{ index .Params "alt" }} -{{else}} - {{ index .Params "caption" }} +It skips the block if the variable is absent, or if it evaluates to +"false" as explained above. + +```go-html-template +{{ with .Params.title }} + <h4>{{ . }}</h4> {{ end }} ``` -#### Example 3: `and` & `or` +#### Example 2: `with` .. `else` -``` -{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} +Below snippet uses the "description" front-matter parameter's value if +set, else uses the default `.Summary` [Page variable][pagevars]: + + +```go-html-template +{{ with .Param "description" }} + {{ . }} +{{ else }} + {{ .Summary }} +{{ end }} ``` -#### Example 4: `with` +See the [`.Param` function][param]. -An alternative way of writing "`if`" and then referencing the same value -is to use "`with`" instead. `with` rebinds the context `.` within its scope -and skips the block if the variable is absent. +#### Example 3: `if` -The first example above could be simplified as: +An alternative (and a more verbose) way of writing `with` is using +`if`. Here, the `.` does not get rebinded. +Below example is "Example 1" rewritten using `if`: + +```go-html-template +{{ if isset .Params "title" }} + <h4>{{ index .Params "title" }}</h4> +{{ end }} ``` -{{ with .Params.title }}<h4>{{ . }}</h4>{{ end }} -``` -#### Example 5: `if` … `else if` +#### Example 4: `if` .. `else` + +Below example is "Example 2" rewritten using `if` .. `else`, and using +[`isset` function][isset] + `.Params` variable (different from the +[`.Param` **function**][param]) instead: +```go-html-template +{{ if (isset .Params "description") }} + {{ index .Params "description" }} +{{ else }} + {{ .Summary }} +{{ end }} ``` -{{ if isset .Params "alt" }} - {{ index .Params "alt" }} -{{ else if isset .Params "caption" }} - {{ index .Params "caption" }} + +#### Example 5: `if` .. `else if` .. `else` + +Unlike `with`, `if` can contain `else if` clauses too. + +```go-html-template +{{ if (isset .Params "description") }} + {{ index .Params "description" }} +{{ else if (isset .Params "summary") }} + {{ index .Params "summary" }} +{{ else }} + {{ .Summary }} {{ end }} ``` +#### Example 6: `and` & `or` + +```go-html-template +{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }} +``` + ## Pipes -One of the most powerful components of Go templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe. +One of the most powerful components of Go Templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe. -Because of the very simple syntax of Go templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline. +Because of the very simple syntax of Go Templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline. A few simple examples should help convey how to use the pipe. @@ -241,26 +336,26 @@ A few simple examples should help convey how to use the pipe. The following two examples are functionally the same: -``` +```go-html-template {{ shuffle (seq 1 5) }} ``` -``` +```go-html-template {{ (seq 1 5) | shuffle }} ``` ### Example 2: `index` -The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function][index], which is built into Go templates: +The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function][index], which is built into Go Templates: -``` +```go-html-template {{ index .Params "disqus_url" | html }} ``` ### Example 3: `or` with `isset` -``` +```go-html-template {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }} Stuff Here {{ end }} @@ -268,7 +363,7 @@ Stuff Here Could be rewritten as -``` +```go-html-template {{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }} Stuff Here {{ end }} @@ -278,7 +373,7 @@ Stuff Here By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this: -``` +```go-html-template {{ "<!--[if lt IE 9]>" | safeHTML }} <script src="html5shiv.js"></script> {{ "<![endif]-->" | safeHTML }} @@ -286,13 +381,24 @@ By default, Go Templates remove HTML comments from output. This has the unfortun Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional comments, avoiding the tedious task of escaping every double quotes (`"`) inside, as demonstrated in the [examples](http://golang.org/pkg/text/template/#hdr-Examples) in the Go text/template documentation: -``` +```go-html-template {{ `<!--[if lt IE 7]><html class="no-js lt-ie9 lt-ie8 lt-ie7"><![endif]-->` | safeHTML }} ``` -## Context (aka "the dot") +## Context (aka "the dot") {#the-dot} + +The most easily overlooked concept to understand about Go Templates is +that `{{ . }}` always refers to the **current context**. -The most easily overlooked concept to understand about Go templates is that `{{ . }}` always refers to the current context. In the top level of your template, this will be the data set made available to it. Inside of an iteration, however, it will have the value of the current item in the loop; i.e., `{{ . }}` will no longer refer to the data available to the entire page. If you need to access page-level data (e.g., page params set in front matter) from within the loop, you will likely want to do one of the following: +- In the top level of your template, this will be the data set made + available to it. +- Inside of an iteration, however, it will have the value of the + current item in the loop; i.e., `{{ . }}` will no longer refer to + the data available to the entire page. + +If you need to access page-level data (e.g., page params set in front +matter) from within the loop, you will likely want to do one of the +following: ### 1. Define a Variable Independent of Context @@ -337,9 +443,9 @@ The built-in magic of `$` would cease to work if someone were to mischievously r Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter. -For instance, the following Go template will include the newlines and horizontal tab in its HTML output: +For instance, the following Go Template will include the newlines and horizontal tab in its HTML output: -``` +```go-html-template <div> {{ .Title }} </div> @@ -347,7 +453,7 @@ For instance, the following Go template will include the newlines and horizontal Which will output: -``` +```html <div> Hello, World! </div> @@ -355,7 +461,7 @@ Which will output: Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline: -``` +```go-html-template <div> {{- .Title -}} </div> @@ -363,11 +469,11 @@ Leveraging the `-` in the following example will remove the extra white space su Which then outputs: -``` +```html <div>Hello, World!</div> ``` -Go considers the following characters whitespace: +Go considers the following characters _whitespace_: * <kbd>space</kbd> * horizontal <kbd>tab</kbd> @@ -378,13 +484,13 @@ Go considers the following characters whitespace: In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo. -### Go templates comments +### Go Templates comments -Go templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered. +Go Templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered. For example: -``` +```go-html-template Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott. ``` @@ -394,24 +500,24 @@ Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2` If you need to produce HTML comments from your templates, take a look at the [Internet Explorer conditional comments](#ie-conditional-comments) example. If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`. For example: -``` +```go-html-template {{ printf "<!-- Our website is named: %s -->" .Site.Title | safeHTML }} ``` -#### HTML comments containing Go templates +#### HTML comments containing Go Templates HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process. {{% note %}} -Do **not** try to comment out Go template code using HTML comments. +Do **not** try to comment out Go Template code using HTML comments. {{% /note %}} -``` +```go-html-template <!-- {{ $author := "Emma Goldman" }} was a great woman. --> {{ $author }} ``` -The templating engine will strip the content within the HTML comment, but will first evaluate any Go template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error. +The templating engine will strip the content within the HTML comment, but will first evaluate any Go Template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error. ## Hugo Parameters @@ -423,7 +529,7 @@ You can provide variables to be used by templates in individual content's [front An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`. -Here is the example front matter: +Here is the example front matter (YAML): ``` --- @@ -447,7 +553,7 @@ Here is an example of corresponding code that could be used inside a `toc.html` {{.TableOfContents}} </aside> <a href="#" id="toc-toggle"></a> -{{end}} +{{ end }} {{< /code >}} We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`. @@ -467,31 +573,33 @@ params: Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates. -``` -{{if .Site.Params.copyrighthtml}}<footer> -<div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div> -</footer>{{end}} +```go-html-template +{{ if .Site.Params.copyrighthtml }} + <footer> + <div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div> + </footer> +{{ end }} ``` An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent: {{< code file="layouts/partials/twitter.html" >}} -{{with .Site.Params.twitteruser}} -<div> - <a href="https://twitter.com/{{.}}" rel="author"> - <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a> -</div> -{{end}} +{{ with .Site.Params.twitteruser }} + <div> + <a href="https://twitter.com/{{.}}" rel="author"> + <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a> + </div> +{{ end }} {{< /code >}} Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable. -``` +```go-html-template <nav> <h1>Recent Posts</h1> <ul> {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}} - <li><a href="{{.RelPermalink}}">{{.Title}}</a></li> + <li><a href="{{.RelPermalink}}">{{.Title}}</a></li> {{- end -}} </ul> </nav> @@ -505,16 +613,16 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function] <h4>Upcoming Events</h4> <ul class="upcoming-events"> {{ range where .Pages.ByDate "Section" "events" }} - {{ if ge .Date.Unix .Now.Unix }} - <li> - <!-- add span for event type --> - <span>{{ .Type | title }} —</span> - {{ .Title }} on - <!-- add span for event date --> - <span>{{ .Date.Format "2 January at 3:04pm" }}</span> - at {{ .Params.place }} - </li> - {{ end }} + {{ if ge .Date.Unix now.Unix }} + <li> + <!-- add span for event type --> + <span>{{ .Type | title }} —</span> + {{ .Title }} on + <!-- add span for event date --> + <span>{{ .Date.Format "2 January at 3:04pm" }}</span> + at {{ .Params.place }} + </li> + {{ end }} {{ end }} </ul> {{< /code >}} @@ -535,7 +643,10 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function] [relpermalink]: /variables/page/ [safehtml]: /functions/safehtml/ [sitevars]: /variables/site/ +[pagevars]: /variables/page/ [variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates." [where]: /functions/where/ [with]: /functions/with/ [godocsindex]: http://golang.org/pkg/text/template/ "Godocs page for index function" +[param]: /functions/param/ +[isset]: /functions/isset/ diff --git a/docs/content/en/templates/taxonomy-templates.md b/docs/content/en/templates/taxonomy-templates.md index 284500e00..d1f9e380f 100644 --- a/docs/content/en/templates/taxonomy-templates.md +++ b/docs/content/en/templates/taxonomy-templates.md @@ -66,7 +66,7 @@ A Taxonomy is a `map[string]WeightedPages`. Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order. -``` +```go []struct { Name string WeightedPages WeightedPages @@ -91,7 +91,7 @@ Each element of the slice has: WeightedPages is simply a slice of WeightedPage. -``` +```go type WeightedPages []WeightedPage ``` @@ -103,16 +103,16 @@ type WeightedPages []WeightedPage ## Displaying custom metadata in Taxonomy Terms Templates -If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such: +If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such: -``` +```go-html-template <ul> - {{ range .Pages }} - <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> - {{ .Params.wikipedia }} - </li> - {{ end }} + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + {{ .Params.wikipedia }} + </li> + {{ end }} </ul> ``` @@ -124,34 +124,46 @@ Taxonomies can be ordered by either alphabetical key or by the number of content ### Order Alphabetically Example -``` +```go-html-template <ul> - {{ $data := .Data }} - {{ range $key, $value := .Data.Terms.Alphabetical }} - <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li> - {{ end }} + {{ $type := .Type }} + {{ range $key, $value := .Data.Terms.Alphabetical }} + {{ $name := .Name }} + {{ $count := .Count }} + {{ with $.Site.GetPage (printf "/%s/%s" $type $name) }} + <li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li> + {{ end }} + {{ end }} </ul> ``` ### Order by Popularity Example -``` +```go-html-template <ul> - {{ $data := .Data }} - {{ range $key, $value := .Data.Terms.ByCount }} - <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li> - {{ end }} + {{ $type := .Type }} + {{ range $key, $value := .Data.Terms.ByCount }} + {{ $name := .Name }} + {{ $count := .Count }} + {{ with $.Site.GetPage (printf "/%s/%s" $type $name) }} + <li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li> + {{ end }} + {{ end }} </ul> ``` ### Order by Least Popular Example -``` +```go-html-template <ul> - {{ $data := .Data }} - {{ range $key, $value := .Data.Terms.ByCount.Reverse }} - <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li> - {{ end }} + {{ $type := .Type }} + {{ range $key, $value := .Data.Terms.ByCount.Reverse }} + {{ $name := .Name }} + {{ $count := .Count }} + {{ with $.Site.GetPage (printf "/%s/%s" $type $name) }} + <li><a href="{{ .Permalink }}">{{ $name }}</a> {{ |