diff options
Diffstat (limited to 'content/templates')
| -rw-r--r-- | content/templates/404.md | 41 | ||||
| -rw-r--r-- | content/templates/content.md | 161 | ||||
| -rw-r--r-- | content/templates/functions.md | 164 | ||||
| -rw-r--r-- | content/templates/go-templates.md | 379 | ||||
| -rw-r--r-- | content/templates/homepage.md | 78 | ||||
| -rw-r--r-- | content/templates/list.md | 338 | ||||
| -rw-r--r-- | content/templates/overview.md | 72 | ||||
| -rw-r--r-- | content/templates/partials.md | 103 | ||||
| -rw-r--r-- | content/templates/rss.md | 100 | ||||
| -rw-r--r-- | content/templates/sitemap.md | 52 | ||||
| -rw-r--r-- | content/templates/terms.md | 160 | ||||
| -rw-r--r-- | content/templates/variables.md | 82 | ||||
| -rw-r--r-- | content/templates/views.md | 127 |
13 files changed, 1857 insertions, 0 deletions
diff --git a/content/templates/404.md b/content/templates/404.md new file mode 100644 index 0000000..1591782 --- /dev/null +++ b/content/templates/404.md @@ -0,0 +1,41 @@ +--- +aliases: +- /layout/404/ +date: 2013-08-21 +linktitle: "404" +menu: + main: + parent: layout +next: /taxonomies/overview +notoc: true +prev: /templates/sitemap +title: 404.html Templates +weight: 100 +--- + +When using Hugo with [GitHub Pages](http://pages.github.com/) you can provide +your own 404 template by creating a 404.html file in the root. + +404 pages are of the type "node" and have all the [node +variables](/layout/variables/) available to use in the templates. + +In addition to the standard node variables, the homepage has access to +all site content accessible from .Data.Pages + + ▾ layouts/ + 404.html + +## 404.html +This is a basic example of a 404.html template: + + {{ partial "header.html" . }} + {{ partial "subheader.html" . }} + + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + </div> + </section> + + {{ partial "footer.html" }} + diff --git a/content/templates/content.md b/content/templates/content.md new file mode 100644 index 0000000..14d613c --- /dev/null +++ b/content/templates/content.md @@ -0,0 +1,161 @@ +--- +aliases: +- /layout/functions/ +date: 2013-07-01 +linktitle: Single Content +menu: + main: + parent: layout +next: /templates/list +prev: /templates/variables +title: Single Content Template +weight: 30 +--- + +The primary view of content in Hugo is the single view. Hugo, for every +Markdown file provided, will render it with a single template. + + +## Which Template will be rendered? +Hugo uses a set of rules to figure out which template to use when +rendering a specific page. + +Hugo will use the following prioritized list. If a file isn’t present, +then the next one in the list will be used. This enables you to craft +specific layouts when you want to without creating more templates +than necessary. For most sites only the \_default file at the end of +the list will be needed. + +Users can specify the `type` and `layout` in the [front-matter](/content/front-matter). `Section` +is determined based on the content file’s location. If `type` is provide, +it will be used instead of `section`. + +### Single + +* /layouts/`TYPE`-or-`SECTION`/`LAYOUT`.html +* /layouts/`TYPE`-or-`SECTION`/single.html +* /layouts/\_default/single.html +* /themes/`THEME`/layouts/`TYPE`-or-`SECTION`/`LAYOUT`.html +* /themes/`THEME`/layouts/`TYPE`-or-`SECTION`/single.html +* /themes/`THEME`/layouts/\_default/single.html + +## Example Single Template File + +Content pages are of the type "page" and have all the [page +variables](/layout/variables/) and [site +variables](/templates/variables/) available to use in the templates. + +In the following examples we have created two different content types as well as +a default content type. + +The default content template to be used in the event that a specific +template has not been provided for that type. The default type works the +same as the other types, but the directory must be called "\_default". + + ▾ layouts/ + ▾ _default/ + single.html + ▾ post/ + single.html + ▾ project/ + single.html + + +## post/single.html +This content template is used for [spf13.com](http://spf13.com). +It makes use of [partial templates](/layout/partials) + + {{ partial "header.html" . }} + {{ partial "subheader.html" . }} + {{ $baseurl := .Site.BaseUrl }} + + <section id="main"> + <h1 id="title">{{ .Title }}</h1> + <div> + <article id="content"> + {{ .Content }} + </article> + </div> + </section> + + <aside id="meta"> + <div> + <section> + <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4> + <h5 id="wc"> {{ .FuzzyWordCount }} Words </h5> + </section> + <ul id="categories"> + {{ range .Params.topics }} + <li><a href="{{ $baseurl }}/topics/{{ . | urlize }}">{{ . }}</a> </li> + {{ end }} + </ul> + <ul id="tags"> + {{ range .Params.tags }} + <li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> </li> + {{ end }} + </ul> + </div> + <div> + {{ if .Prev }} + <a class="previous" href="{{.Prev.Permalink}}"> {{.Prev.Title}}</a> + {{ end }} + {{ if .Next }} + <a class="next" href="{{.Next.Permalink}}"> {{.Next.Title}}</a> + {{ end }} + </div> + </aside> + + {{ partial "disqus.html" . }} + {{ partial "footer.html" . }} + + +## project/single.html +This content template is used for [spf13.com](http://spf13.com). +It makes use of [partial templates](/layout/partials) + + + {{ partial "header.html" . }} + {{ partial "subheader.html" . }} + {{ $baseurl := .Site.BaseUrl }} + + <section id="main"> + <h1 id="title">{{ .Title }}</h1> + <div> + <article id="content"> + {{ .Content }} + </article> + </div> + </section> + + <aside id="meta"> + <div> + <section> + <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4> + <h5 id="wc"> {{ .FuzzyWordCount }} Words </h5> + </section> + <ul id="categories"> + {{ range .Params.topics }} + <li><a href="{{ $baseurl }}/topics/{{ . | urlize }}">{{ . }}</a> </li> + {{ end }} + </ul> + <ul id="tags"> + {{ range .Params.tags }} + <li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> </li> + {{ end }} + </ul> + </div> + </aside> + + {{if isset .Params "project_url" }} + <div id="ribbon"> + <a href="{{ index .Params "project_url" }}" rel="me">Fork me on GitHub</a> + </div> + {{ end }} + + {{ partial "footer.html" }} + +Notice how the project/single.html template uses an additional parameter unique +to this template. This doesn't need to be defined ahead of time. If the key is +present in the front matter than it can be used in the template. To +easily generate new content of this type with these keys ready use +[content archetypes](/content/archetypes). diff --git a/content/templates/functions.md b/content/templates/functions.md new file mode 100644 index 0000000..4d4d933 --- /dev/null +++ b/content/templates/functions.md @@ -0,0 +1,164 @@ +--- +aliases: +- /layout/functions/ +date: 2013-07-01 +linktitle: Functions +menu: + main: + parent: layout +next: /templates/variables +prev: /templates/go-templates +title: Hugo Template Functions +weight: 20 +--- + +Hugo uses the excellent Go html/template library for its template engine. +It is an extremely lightweight engine that provides a very small amount of +logic. In our experience it is just the right amount of logic to be able +to create a good static website. + +Go templates are lightweight but extensible. Hugo has added the following +functions to the basic template logic. + +(Go itself supplies built-in functions, including comparison operators +and other basic tools; these are listed in the +[Go template documentation](http://golang.org/pkg/text/template/#hdr-Functions).) + +## General + +### isset +Return true if the parameter is set. +Takes either a slice, array or channel and an index or a map and a key as input. + +e.g. {{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }} + +### echoParam +If parameter is set, then echo it. + +e.g. {{echoParam .Params "project_url" }} + +### eq +Return true if the parameters are equal. + +e.g. + {{ if eq .Section "blog" }}current{{ end}}" + +### first +Slices an array to only the first X elements. + +Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/) + +e.g. + {{ range first 10 .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + +### where +Filters an array to only elements containing a matching value for a given field. + +Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/) + +e.g. + + {{ range where .Data.Pages "Section" "post" }} + {{ .Content}} + {{ end }} + +*where and first can be stacked* + +e.g. + + {{ range first 5 (where .Data.Pages "Section" "post") }} + {{ .Content}} + {{ end }} + +### in +Checks if an element is in an array (or slice) and returns a boolean. The elements supported are strings, integers and floats (only float64 will match as expected). In addition, it can also check if a substring exists in a string. + +e.g. + {{ if in .Params.tags "Git" }}Follow me on GitHub!{{ end }} +or + {{ if in "this string contains a substring" "substring" }}Substring found!{{ end }} + +### intersect +Given two arrays (or slices), this function will return the common elements in the arrays. The elements supported are strings, integers and floats (only float64). + +A useful example of this functionality is a 'similar posts' block. Create a list of links to posts where any of the tags in the current post match any tags in other posts. + +e.g. + <ul> + {{ $page_link := .Permalink }} + {{ $tags := .Params.tags }} + {{ range .Site.Recent }} + {{ $page := . }} + {{ $has_common_tags := intersect $tags .Params.tags | len | lt 0 }} + {{ if and $has_common_tags (ne $page_link $page.Permalink) }} + <li><a href="{{ $page.Permalink }}">{{ $page.Title }}</a></li> + {{ end }} + {{ end }} + </ul> + + +## Math + +### add +Adds two integers. + +e.g. {{add 1 2}} → 3 + +### sub +Subtracts two integers. + +e.g. {{sub 3 2}} → 1 + +### div +Divides two integers. + +e.g. {{div 6 3}} → 2 + +### mul +Multiplies two integers. + +e.g. {{mul 2 3}} → 6 + +### mod +Modulus of two integers. + +e.g. {{mod 15 3}} → 0 + +### modBool +Boolean of modulus of two integers. +true if modulus is 0. + +e.g. {{modBool 15 3}} → true + +## Strings + +### urlize +Takes a string and sanitizes it for usage in URLs, converts spaces to "-". + +e.g. <a href="/tags/{{ . | urlize }}">{{ . }}</a> + +### safeHtml +Declares the provided string as "safe" so Go templates will not filter it. + +e.g. {{ .Params.CopyrightHTML | safeHtml }} + +### lower +Convert all characters in string to lowercase. + +e.g. {{lower "BatMan"}} → "batman" + +### upper +Convert all characters in string to uppercase. + +e.g. {{upper "BatMan"}} → "BATMAN" + +### title +Convert all characters in string to titlecase. + +e.g. {{title "BatMan"}} → "Batman" + +### highlight +Take a string of code and a language, uses Pygments to return the syntax +highlighted code in HTML. Used in the [highlight shortcode](/extras/highlighting). diff --git a/content/templates/go-templates.md b/content/templates/go-templates.md new file mode 100644 index 0000000..ccfa3a9 --- /dev/null +++ b/content/templates/go-templates.md @@ -0,0 +1,379 @@ +--- +aliases: +- /layout/go-templates/ +- /layouts/go-templates/ +date: 2013-07-01 +menu: + main: + parent: layout +next: /templates/functions +prev: /templates/overview +title: Go Template Primer +weight: 15 +--- + +Hugo uses the excellent [Go][] [html/template][gohtmltemplate] library for +its template engine. It is an extremely lightweight engine that provides a very +small amount of logic. In our experience it is just the right amount of +logic to be able to create a good static website. If you have used other +template systems from different languages or frameworks, you will find a lot of +similarities in Go templates. + +This document is a brief primer on using Go templates. The [Go docs][gohtmltemplate] +go into more depth and cover features that aren't mentioned here. + +## Introduction to Go Templates + +Go templates provide an extremely simple template language. It adheres to the +belief that only the most basic of logic belongs in the template or view layer. +One consequence of this simplicity is that Go templates parse very quickly. + +A unique characteristic of Go templates is they are content aware. Variables and +content will be sanitized depending on the context of where they are used. More +details can be found in the [Go docs][gohtmltemplate]. + +## Basic Syntax + +Go lang templates are HTML files with the addition of variables and +functions. + +**Go variables and functions are accessible within {{ }}** + +Accessing a predefined variable "foo": + + {{ foo }} + +**Parameters are separated using spaces** + +Calling the `add` function with input of 1, 2: + + {{ add 1 2 }} + +**Methods and fields are accessed via dot notation** + +Accessing the Page Parameter "bar" + + {{ .Params.bar }} + +**Parentheses can be used to group items together** + + {{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} + + +## Variables + +Each Go template has a struct (object) made available to it. In Hugo, each +template is passed either a page or a node struct depending on which type of +page you are rendering. More details are available on the +[variables](/layout/variables) page. + +A variable is accessed by referencing the variable name. + + <title>{{ .Title }}</title> + +Variables can also be defined and referenced. + + {{ $address := "123 Main St."}} + {{ $address }} + + +## Functions + +Go template ships with a few functions which provide basic functionality. The Go +template system also provides a mechanism for applications to extend the +available functions with their own. [Hugo template +functions](/layout/functions) provide some additional functionality we believe +are useful for 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** + + {{ add 1 2 }} + +**Example 2: Comparing numbers** + + {{ lt 1 2 }} + +(There are more boolean operators, detailed in the +[template documentation](http://golang.org/pkg/text/template/#hdr-Functions).) + +## Includes + +When including another template, you will pass to it the data it will be +able to access. To pass along the current context, please remember to +include a trailing dot. The templates location will always be starting at +the /layout/ directory within Hugo. + +**Example:** + + {{ template "partials/header.html" . }} + +And, starting with Hugo v0.12, you may also use the `partial` call +for [partial templates](/templates/partials/): + + {{ partial "header.html" . }} + + +## 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. + +**Example 1: Using Context** + + {{ range array }} + {{ . }} + {{ end }} + +**Example 2: Declaring value variable name** + + {{range $element := array}} + {{ $element }} + {{ end }} + +**Example 2: Declaring key and value variable name** + + {{range $index, $element := array}} + {{ $index }} + {{ $element }} + {{ end }} + +### Conditionals + +`if`, `else`, `with`, `or` & `and` provide the framework for handling conditional +logic in Go Templates. Like `range`, each statement is closed with `end`. + +Go Templates treat the following values as false: + +* false +* 0 +* any array, slice, map, or string of length zero + +**Example 1: `if`** + + {{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }} + +**Example 2: `if` … `else`** + + {{ if isset .Params "alt" }} + {{ index .Params "alt" }} + {{else}} + {{ index .Params "caption" }} + {{ end }} + +**Example 3: `and` & `or`** + + {{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} + +**Example 4: `with`** + +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. + +The first example above could be simplified as: + + {{ with .Params.title }}<h4>{{ . }}</h4>{{ end }} + +**Example 5: `if` … `else if`** + + {{ if isset .Params "alt" }} + {{ index .Params "alt" }} + {{ else if isset .Params "caption" }} + {{ index .Params "caption" }} + {{ end }} + +## 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. + +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 only can 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. + +**Example 1:** + + {{ if eq 1 1 }} Same {{ end }} + +is the same as + + {{ eq 1 1 | if }} Same {{ end }} + +It does look odd to place the `if` at the end, but it does provide a good +illustration of how to use the pipes. + +**Example 2:** + + {{ index .Params "disqus_url" | html }} + +Access the page parameter called "disqus_url" and escape the HTML. + +**Example 3:** + + {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} + Stuff Here + {{ end }} + +Could be rewritten as + + {{ isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" | if }} + Stuff Here + {{ end }} + +### Internet Explorer conditional comments using Pipes + +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: + + {{ "<!--[if lt IE 9]>" | safeHtml }} + <script src="html5shiv.js"></script> + {{ "<![endif]-->" | safeHtml }} + +## Context (a.k.a. the dot) + +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 a iteration it will have +the value of the current item. When inside of a loop the context has changed. +`.` will no longer refer to the data available to the entire page. If you need +to +access this from within the loop, you will likely want to set it to a variable +instead of depending on the context. + +**Example:** + + {{ $title := .Site.Title }} + {{ range .Params.tags }} + <li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> - {{ $title }} </li> + {{ end }} + +Notice how once we have entered the loop the value of `{{ . }}` has changed. We +have defined a variable outside of the loop so we have access to it from within +the loop. + +# Hugo Parameters + +Hugo provides the option of passing values to the template language +through the site configuration (for sitewide values), or through the meta +data of each specific piece of content. You can define any values of any +type (supported by your front matter/config format) and use them however +you want to inside of your templates. + + +## Using Content (page) Parameters + +In each piece of content, you can provide variables to be used by the +templates. This happens in the [front matter](/content/front-matter). + +An example of this is used in this documentation site. Most of the pages +benefit from having the table of contents provided. Sometimes the TOC just +doesn't make a lot of sense. We've defined a variable in our front matter +of some pages to turn off the TOC from being displayed. + +Here is the example front matter: + +``` +--- +title: "Permalinks" +date: "2013-11-18" +aliases: + - "/doc/permalinks/" +groups: ["extras"] +groups_weight: 30 +notoc: true +--- +``` + +Here is the corresponding code inside of the template: + + {{ if not .Params.notoc }} + <div id="toc" class="well col-md-4 col-sm-6"> + {{ .TableOfContents }} + </div> + {{ end }} + + + +## Using Site (config) Parameters +In your top-level configuration file (e.g., `config.yaml`) you can define site +parameters, which are values which will be available to you in partials. + +For instance, you might declare: + +```yaml +params: + CopyrightHTML: "Copyright © 2013 John Doe. All Rights Reserved." + TwitterUser: "spf13" + SidebarRecentLimit: 5 +``` + +Within a footer layout, you might then declare a `<footer>` which is only +provided if the `CopyrightHTML` parameter is provided, and if it is given, +you would declare it to be HTML-safe, 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}} +``` + +An alternative way of writing the "`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: + +``` +{{with .Site.Params.TwitterUser}}<span class="twitter"> +<a href="https://twitter.com/{{.}}" rel="author"> +<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" + alt="Twitter"></a> +</span>{{end}} +``` + +Finally, if you want to pull "magic constants" out of your layouts, you can do +so, such as in this example: + +``` +<nav class="recent"> + <h1>Recent Posts</h1> + <ul>{{range first .Site.Params.SidebarRecentLimit .Site.Recent}} + <li><a href="{{.RelPermalink}}">{{.Title}}</a></li> + {{end}}</ul> +</nav> +``` + + +[go]: http://golang.org/ +[gohtmltemplate]: http://golang.org/pkg/html/template/ + +# Template example: Show only upcoming events + +Go allows you to do more than what's shown here. Using Hugo's +[`where`](/templates/functions/#toc_4) function and Go built-ins, we can list +only the items from `content/events/` whose date (set in the front matter) is in +the future: + + <h4>Upcoming Events</h4> + <ul class="upcoming-events"> + {{ range where .Data.Pages.ByDate "Section" "events" }} + {{ if ge .Date.Unix .Now.Unix }} + <li><span class="event-type">{{ .Type | title }} —</span> + {{ .Title }} + on <span class="event-date"> + {{ .Date.Format "2 January at 3:04pm" }}</span> + at {{ .Params.place }} + </li> + {{ end }} + {{ end }} diff --git a/content/templates/homepage.md b/content/templates/homepage.md new file mode 100644 index 0000000..f4dfc76 --- /dev/null +++ b/content/templates/homepage.md @@ -0,0 +1,78 @@ +--- +aliases: +- /layout/homepage/ +date: 2013-07-01 +menu: + main: + parent: layout +next: /templates/terms +notoc: true +prev: /templates/list +title: Homepage +weight: 50 +--- + +The home page of a website is often formatted differently than the other +pages. In Hugo you can define your own homepage template. + +Homepage is of the type "node" and have all the [node +variables](/templates/variables/) and [site +variables](/templates/variables/) available to use in the templates. + +*This is the only required template for building a site and useful when +bootstrapping a new site and template. It is also the only required +template when using a single page site.* + +In addition to the standard node variables, the homepage has access to +all site content accessible from `.Data.Pages`. Details on how to use the +list of pages can be found in the [Lists Template](/templates/list/). + +## Which Template will be rendered? +Hugo uses a set of rules to figure out which template to use when +rendering a specific page. + +Hugo will use the following prioritized list. If a file isn’t present, +then the next one in the list will be used. This enables you to craft +specific layouts when you want to without creating more templates +than necessary. For most sites, only the \_default file at the end of +the list will be needed. + +* /layouts/index.html +* /layouts/\_default/list.html +* /layouts/\_default/single.html +* /themes/`THEME`/layouts/index.html +* /themes/`THEME`/layouts/\_default/list.html +* /themes/`THEME`/layouts/\_default/single.html + +## Example index.html +This content template is used for [spf13.com](http://spf13.com). + +It makes use of [partial templates](/templates/partials) and uses a similar approach as a [List](/templates/list/). + + <!DOCTYPE html> + <html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#"> + <head> + <meta charset="utf-8"> + + {{ partial "meta.html" . }} + + <base href="{{ .Site.BaseUrl }}"> + <title>{{ .Site.Title }}</title> + <link rel="canonical" href="{{ .Permalink }}"> + <link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" /> + + {{ partial "head_includes.html" . }} + </head> + <body lang="en"> + + {{ partial "subheader.html" . }} + + <section id="main"> + <div> + {{ range first 10 .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + </div> + </section> + + {{ partial "footer.html" }} diff --git a/content/templates/list.md b/content/templates/list.md new file mode 100644 index 0000000..c4c0bc2 --- /dev/null +++ b/content/templates/list.md @@ -0,0 +1,338 @@ +--- +aliases: +- /layout/indexes/ +date: 2013-07-01 +linktitle: List of Content +menu: + main: + parent: layout +next: /templates/homepage +prev: /templates/content +title: Content List Template +weight: 40 +--- + +A list template is any template that will be used to render multiple pieces of +content in a single HTML page (with the exception of the [homepage](/layout/homepage) which has a +dedicated template). + +We are using the term list in its truest sense, a sequential arrangement +of material, especially in alphabetical or numerical order. Hugo uses +list templates to render anyplace where content is being listed such as +taxonomies and sections. + +## Which Template will be rendered? + +Hugo uses a set of rules to figure out which template to use when +rendering a specific page. + +Hugo will use the following prioritized list. If a file isn’t present, +then the next one in the list will be used. This enables you to craft +specific layouts when you want to without creating more templates +than necessary. For most sites only the \_default file at the end of +the list will be needed. + + +### Section Lists + +A Section will be rendered at /`SECTION`/ + +* /layouts/section/`SECTION`.html +* /layouts/\_default/section.html +* /layouts/\_default/list.html +* /themes/`THEME`/layouts/section/`SECTION`.html +* /themes/`THEME`/\_default/section.html +* /themes/`THEME`/layouts/\_default/list.html + + +### Taxonomy Lists + +A Taxonomy will be rendered at /`PLURAL`/`TERM`/ + +* /layouts/taxonomy/`SINGULAR`.html +* /layouts/\_default/taxonomy.html +* /layouts/\_default/list.html +* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.html +* /themes/`THEME`/\_default/taxonomy.html +* /themes/`THEME`/layouts/\_default/list.html + +### Section RSS + +A Section’s RSS will be rendered at /`SECTION`/index.xml + +*Hugo ships with its own ATOM 2.0 RSS template. In most cases this will +be sufficient, and an RSS template will not need to be provided by the +user.* + +Hugo provides the ability for you to define any RSS type you wish, and +can have different RSS files for each section and taxonomy. + +* /layouts/section/`SECTION`.rss.xml +* /layouts/\_default/rss.xml +* /themes/`THEME`/layouts/section/`SECTION`.rss.xml +* /themes/`THEME`/layouts/\_default/rss.xml + +### Taxonomy RSS + +A Taxonomy’s RSS will be rendered at /`PLURAL`/`TERM`/index.xml + +*Hugo ships with its own ATOM 2.0 RSS template. In most cases this will +be sufficient, and an RSS template will not need to be provided by the +user.* + +Hugo provides the ability for you to define any RSS type you wish, and +can have different RSS files for each section and taxonomy. + +* /layouts/taxonomy/`SINGULAR`.rss.xml +* /layouts/\_default/rss.xml +* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.rss.xml +* /themes/`THEME`/layouts/\_default/rss.xml + + +## Variables + +List pages are of the type "node" and have all the [node +variables](/templates/variables/) and [site +variables](/templates/variables/) available to use in the templates. + +Taxonomy pages will additionally have: + +**.Data.`singular`** The taxonomy itself.<br> + +## Example List Template Pages + +### Example section template (post.html) +This content template is used for [spf13.com](http://spf13.com). +It makes use of [partial templates](/templates/partials). All examples use a +[view](/templates/views/) called either "li" or "summary" which this example site +defined. + + {{ partial "header.html" . }} + {{ partial "subheader.html" . }} + + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + <ul id="list"> + {{ range .Data.Pages }} + {{ .Render "li"}} + {{ end }} + </ul> + </div> + </section> + + {{ partial "footer.html" }} + +### Example taxonomy template (tag.html) +This content template is used for [spf13.com](http://spf13.com). +It makes use of [partial templates](/templates/partials). All examples use a +[view](/templates/views/) called either "li" or "summary" which this example site +defined. + + {{ partial "header.html" . }} + {{ partial "subheader.html" . }} + + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + </div> + </section> + + {{ partial "footer.html" }} + +## Ordering Content + +In the case of Hugo each list will render the content based on metadata provided in the [front +matter](/content/front-matter). See [ordering content](/content/ordering) for more information. + +Here are a variety of different ways you can order the content items in +your list templates: + +### Order by Weight -> Date (default) + + {{ range .Data.Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + +### Order by Weight -> Date + + {{ range .Data.Pages.ByWeight }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + +### Order by Date + + {{ range .Data.Pages.ByDate }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + +### Order by Length + + {{ range .Data.Pages.ByLength }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + + +### Order by Title + + {{ range .Data.Pages.ByTitle }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + +### Order by LinkTitle + + {{ range .Data.Pages.ByLinkTitle }} + <li> + <a href="{{ .Permalink }}">{{ .LinkTitle }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + +### Reverse Order +Can be applied to any of the above. Using Date for an example. + + {{ range .Data.Pages.ByDate.Reverse }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + +## Grouping Content + +Hugo provides some grouping functions for list pages. You can use them to +group pages by Section, Date etc. + +Here are a variety of different ways you can group the content items in +your list templates: + +### Grouping by Page field + + {{ range .Data.Pages.GroupBy "Section" }} + <h3>{{ .Key }}</h3> + <ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + </ul> + {{ end }} + +### Grouping by Page date + + {{ range .Data.Pages.GroupByDate "2006-01" }} + <h3>{{ .Key }}</h3> + <ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + </ul> + {{ end }} + +### Reversing Key Order + +The ordering of the groups is performed by keys in alpha-numeric order (A–Z, +1–100) and in reverse chronological order (newest first) for dates. + +While these are logical defaults, they are not always the desired order. There +are two different syntaxes to change the order, they both work the same way, so +it’s really just a matter of preference. + +#### Reverse method + + {{ range (.Data.Pages.GroupBy "Section").Reverse }} + ... + + {{ range (.Data.Pages.GroupByDate "2006-01").Reverse }} + ... + + +#### Providing the (alternate) direction + + {{ range .Data.Pages.GroupByDate "2006-01" "asc" }} + ... + + {{ range .Data.Pages.GroupBy "Section" "desc" }} + ... + +### Ordering Pages within Group + +Because Grouping returns a key and a slice of pages, all of the ordering methods listed above are available. + +In this example I’ve ordered the groups in chronological order and the content +within each group in alphabetical order by title. + + {{ range .Data.Pages.GroupByDate "2006-01" "asc" }} + <h3>{{ .Key }}</h3> + <ul> + {{ range .Pages.ByTitle }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} + </ul> + {{ end }} + +## Filtering & Limiting Content + +Sometimes you only want to list a subset of the available content. A common +request is to only display “Posts” on the homepage. Using the `where` function +you can do just that. + +### First + +`first` works like the `limit` keyword in SQL. It reduces the array to only the +first X elements. It takes the array and number of elements as input. + + {{ range first 10 .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + +### Where + +`where` works in a similar manner to the `where` keyword in SQL. It selects all +elements of the slice that match the provided field and value. It takes three +arguments 'array or slice of maps or structs', 'key or field name' and 'match +value' + + {{ range where .Data.Pages "Section" "post" }} + {{ .Content}} + {{ end }} + +### First & Where Together + +Using both together can be very powerful. + + {{ range first 5 (where .Data.Pages "Section" "post") }} + {{ .Content}} + {{ end }} + +If `where` or `first` receives invalid input or a field name that doesn’t exist they will provide an error and stop site generation. + +These are both template functions and work on not only +[lists](/templates/list/), but [taxonomies](/taxonomies/displaying/), +[terms](/templates/terms/) and [groups](/templates/list/). diff --git a/content/templates/overview.md b/content/templates/overview.md new file mode 100644 index 0000000..d0eabb5 --- /dev/null +++ b/content/templates/overview.md @@ -0,0 +1,72 @@ +--- +aliases: +- /doc/templates/ +- /layout/templates/ +- /layout/overview/ +date: 2013-07-01 +linktitle: Overview +menu: + main: + parent: layout +next: /templates/go-templates +prev: /themes/creation +title: Hugo Templates +weight: 10 +--- + +Hugo uses the excellent Go html/template library for its template engine. +It is an extremely lightweight engine that provides a very small amount of +logic. In our experience it is just the right amount of logic to be able +to create a good static website. + +While Hugo has a number of different template roles, most complete +websites can be built using just a small number of template files. +Please don’t be afraid of the variety of different template roles. They +enable Hugo to build very complicated sites. Most sites will only +need to create a [/layouts/\_default/single.html](/templates/content) & [/layouts/\_default/list.html](/templates/list) + +If you are new to Go's templates, the [Go Template Primer](/layout/go-templates) +is a great place to start. + +If you are familiar with Go’s templates, Hugo provides some [additional +template functions](/templates/functions) and [variables](/templates/variables) you will want to be familiar +with. + +## Primary Template roles + +There are 3 primary kinds of templates that Hugo works with. + +### [Single](/templates/content) +Render a single piece of content + +### [List](/templates/list) +Page that list multiple pieces of content + +### [Homepage](/templates/homepage/) +The homepage of your site + +## Supporting Template Roles (optional) + +Hugo also has additional kinds of templates all of which are optional + +### [Partial Templates](/templates/partials) +Common page parts to be included in the above mentioned templates + +### [Content Views](/templates/views) +Different ways of rendering a (single) content type + +### [Taxonomy Terms](/templates/terms) +A list of the terms used for a specific taxonomy, e.g. a Tag cloud + +## Other Templates (generally unnecessary) + +### [RSS](/templates/rss/) +Used to render all rss documents + +### [Sitemap](/templates/sitemap/) +Used to render the XML sitemap + +### [404](/templates/404) +This template will create a 404.html page used when hosting on GitHub Pages + + diff --git a/content/templates/partials.md b/content/templates/partials.md new file mode 100644 index 0000000..e5a4186 --- /dev/null +++ b/content/templates/partials.md @@ -0,0 +1,103 @@ +--- +aliases: +- /layout/chrome/ +date: 2013-07-01 +menu: + main: + parent: layout +next: /templates/rss +prev: /templates/views +title: Partial Templates +weight: 80 +--- + +In practice, it's very convenient to split out common template portions into a +partial template that can be included anywhere. As you create the rest of your +templates, you will include templates from the /layout/partials directory. + +Partials are especially important for themes as it gives users an opportunity +to overwrite just a small part of your theme, while maintaining future compatibility. + +Theme developers may want to include a few partials with empty HTML +files in the theme just so end users have an easy place to inject their +customized content. + +I've found it helpful to include a header and footer template in +partials so I can include those in all the full page layouts. There is +nothing special about header.html and footer.html other than they seem +like good names to use for inclusion in your other templates. + + ▾ layouts/ + ▾ partials/ + header.html + footer.html + +By ensuring that we only reference [variables](/layout/variables/) +used for both nodes and pages, we can use the same partials for both. + +## Partial vs Template + +Version v0.12 of Hugo introduced the `partial` call inside the template system. +This is a change to the way partials were handled previously inside the +template system. In earlier versions, Hugo didn’t treat partials specially, and +you could include a partial template with the `template` call in the standard +template language. + +With the addition of the theme system in v0.11, it became apparent that a theme +& override aware partial was needed. + +When using Hugo v0.12 and above, please use the `partial` call (and leave out +the “partial/” path). The old approach would still work, but wouldn’t benefit from +the ability to have users override the partial theme file with local layouts. + +## Example header.html +This header template is used for [spf13.com](http://spf13.com): + + <!DOCTYPE html> + <html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#"> + <head> + <meta charset="utf-8"> + + {{ partial "meta.html" . }} + + <base href="{{ .Site.BaseUrl }}"> + <title> {{ .Title }} : spf13.com </title> + <link rel="canonical" href="{{ .Permalink }}"> + {{ if .RSSlink }}<link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }} + + {{ partial "head_includes.html" . }} + </head> + <body lang="en"> + +## Example footer.html +This footer template is used for [spf13.com](http://spf13.com): + + <footer> + <div> + <p> + © 2013-14 Steve Francia. + <a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>; + please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>. + </p> + </div> + </footer> + <script type="text/javascript"> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-XYSYXYSY-X']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : + 'http://www') + '.google-analytics.com/ga.js'; + ga.setAttribute('async', 'true'); + document.documentElement.firstChild.appendChild(ga); + })(); + + </script> + </body> + </html> + +**For examples of referencing these templates, see [single content +templates](/templates/content), [list templates](/templates/list) and [homepage templates](/templates/homepage).** diff --git a/content/templates/rss.md b/content/templates/rss.md new file mode 100644 index 0000000..a31b1ad --- /dev/null +++ b/content/templates/rss.md @@ -0,0 +1,100 @@ +--- +aliases: +- /layout/rss/ +date: 2013-07-01 +linktitle: RSS +menu: + main: + parent: layout +next: /templates/sitemap +notoc: one +prev: /templates/partials +title: RSS (feed) Templates +weight: 90 +--- + +Like all other templates, you can use a single RSS template to generate +all of your RSS feeds, or you can create a specific template for each +individual feed. Unlike other templates, *Hugo ships with its own ATOM +2.0 RSS template. In most cases this will be sufficient, and an RSS +template will not need to be provided by the user.* + +RSS pages are of the type "node" and have all the [node +variables](/layout/variables/) available to use in the templates. + + +## Which Template will be rendered? +Hugo uses a set of rules to figure out which template to use when +rendering a specific page. + +Hugo will use the following prioritized list. If a file isn’t present, +then the next one in the list will be used. This enables you to craft +specific layouts when you want to without creating more templates +than necessary. For most sites only the \_default file at the end of +the list will be needed. + +### Main RSS + +* /layouts/rss.xml +* /layouts/\_default/rss.xml +* \__internal/rss.xml + +### Section RSS + +* /layouts/section/`SECTION`.rss.xml +* /layouts/\_default/rss.xml +* /themes/`THEME`/layouts/section/`SECTION`.rss.xml +* /themes/`THEME`/layouts/\_default/rss.xml +* \__internal/rss.xml + +### Taxonomy RSS + +* /layouts/taxonomy/`SINGULAR`.rss.xml +* /layouts/\_default/rss.xml +* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.rss.xml +* /themes/`THEME`/layouts/\_default/rss.xml +* \__internal/rss.xml + + +## Configuring RSS + +If the following are provided in the site’s config file, then they +will be included in the RSS output. Example values are provided. + + languageCode = "en-us" + copyright = "This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License." + + [author] + name = "My Name Here" + + +## The Embedded rss.xml +This is the RSS template that ships with Hugo. It adheres to the +ATOM 2.0 Spec. + + <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> + <channel> + <title>{{ .Title }} on {{ .Site.Title }} </title> + <generator uri="https://gohugo.io">Hugo</generator> + <link>{{ .Permalink }}</link> + {{ with .Site.LanguageCode }}<language>{{.}}</language>{{end}} + {{ with .Site.Author.name }}<author>{{.}}</author>{{end}} + {{ with .Site.Copyright }}<copyright>{{.}}</copyright>{{end}} + <updated>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }}</updated> + {{ range first 15 .Data.Pages }} + <item> + <title>{{ .Title }}</title> + <link>{{ .Permalink }}</link> + <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }}</pubDate> + {{with .Site.Author.name}}<author>{{.}}</author>{{end}} + <guid>{{ .Permalink }}</guid> + <description>{{ .Content | html }}</description> + </item> + {{ end }} + </channel> + </rss> + +*Important: Hugo will automatically add the following header line to this file +on render… please don't include this in the template as it's not valid HTML.* + + <?xml version="1.0" encoding="utf-8" standalone="yes" ?> diff --git a/content/templates/sitemap.md b/content/templates/sitemap.md new file mode 100644 index 0000000..227c078 --- /dev/null +++ b/content/templates/sitemap.md @@ -0,0 +1,52 @@ +--- +aliases: +- /layout/sitemap/ +date: 2014-05-07 +linktitle: Sitemap +menu: + main: + parent: layout +next: /templates/404 +notoc: true +prev: /templates/rss +title: Sitemap Template +weight: 95 +--- + +A single Sitemap template is used to generate the `sitemap.xml` file. +Hugo automatically comes with this template file. **No work is needed on +the users part unless they want to customize the sitemap.xml.** + +This page is of the type "node" and have all the [node +variables](/layout/variables/) available to use in this template +along with Sitemap-specific ones: + +**.Sitemap.ChangeFreq** The page change frequency<br> +**.Sitemap.Priority** The priority of the page<br> + +In addition to the standard node variables, the homepage has access to all +site pages through `.Data.Pages`. + +If provided Hugo will use /layouts/sitemap.xml instead of the internal +one. + +## Hugo’s sitemap.xml + +This template respects the version 0.9 of the [Sitemap +Protocol](http://www.sitemaps.org/protocol.html). + + <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> + {{ range .Data.Pages }} + <url> + <loc>{{ .Permalink }}</loc> + <lastmod>{{ safeHtml ( .Date.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ with .Sitemap.ChangeFreq }} + <changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }} + <priority>{{ .Sitemap.Priority }}</priority>{{ end }} + </url> + {{ end }} + </urlset> + +*Important: Hugo will automatically add the following header line to this file +on render...please don't include this in the template as it's not valid HTML.* + + <?xml version="1.0" encoding="utf-8" standalone="yes" ?> diff --git a/content/templates/terms.md b/content/templates/terms.md new file mode 100644 index 0000000..5c066a4 --- /dev/null +++ b/content/templates/terms.md @@ -0,0 +1,160 @@ +--- +aliases: +- /indexes/lists/ +- /doc/indexes/ +- /extras/indexes +date: 2014-05-21 +linktitle: Taxonomy Terms +menu: + main: + parent: layout +next: /templates/views +prev: /templates/homepage +title: Taxonomy Terms Template +weight: 60 +--- + +A unique template is needed to create a list of the terms for a given +taxonomy. This is different from the [list template](/templates/list/) +as that template is a list of content, where this is a list of meta data. + +## Which Template will be rendered? +Hugo uses a set of rules to figure out which template to use when +rendering a specific page. + +Hugo will use the following prioritized list. If a file isn’t present, +then the next one in the list will be used. This enables you to craft +specific layouts when you want to without creating more templates +than necessary. For most sites only the \_default file at the end of +the list will be needed. + +A Taxonomy Terms List will be rendered at /`PLURAL`/ + +* /layouts/taxonomy/`SINGLE`.terms.html +* /layouts/\_default/terms.html + +If that neither file is found in either the /layouts or /theme/layouts +directory than hugo will not render the taxonomy terms pages. It is also +common for people to render taxonomy terms lists on other pages such as +the homepage or the sidebar (such as a tag cloud) and not have a +dedicated page for the terms. + +## Variables + +Taxonomy Terms pages are of the type "node" and have all the [node +variables](/templates/variables/) and [site +variables](/templates/variables/) available to use in the templates. + +Taxonomy Terms pages will additionally have: + +* **.Data.Singular** The singular name of the taxonomy +* **.Data.Plural** The plural name of the taxonomy +* **.Data.Terms** The taxonomy itself +* **.Data.Terms.Alphabetical** The Terms alphabetized +* **.Data.Terms.ByCount** The Terms ordered by popularity + +## Example terms.html file + +List pages are of the type "node" and have all the [node +variables](/templates/variables/) and [site +variables](/templates/variables/) available to use in the templates. + +This content template is used for [spf13.com](http://spf13.com). +It makes use of [partial templates](/templates/partials). The list of indexes +templates cannot use a [content view](/templates/views) as they don't display the content, but +rather information about the content. + +This particular template lists all of the Tags used on +[spf13.com](http://spf13.com) and provides a count for the number of pieces of +content tagged with each tag. + +`.Data.Terms` is an map of terms ⇒ [contents] + + {{ partial "header.html" . }} + {{ partial "subheader.html" . }} + + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + + <ul> + {{ $data := .Data }} + {{ range $key, $value := .Data.Terms }} + <li><a href="{{ $data.Plural }}/{{ $key | urlize }}"> {{ $key }} </a> {{ len $value }} </li> + {{ end }} + </ul> + </div> + </section> + + {{ partial "footer.html" }} + + +Another example listing the content for each term (ordered by Date) + + + {{ partial "header.html" . }} + {{ partial "subheader.html" . }} + + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + + {{ $data := .Data }} + {{ range $key,$value := .Data.Terms.ByCount }} + <h2><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </h2> + <ul> + {{ range $value.Pages.ByDate }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + </li> + {{ end }} + </ul> + {{ end }} + </div> + </section> + + {{ partial "footer.html" }} + +## Ordering + +Hugo can order the meta data in two different ways. It can be ordered by the +number of content assigned to that key or alphabetically. + + +## Example indexes.html file (alphabetical) + + {{ partial "header.html" . }} + {{ partial "subheader.html" . }} + + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + <ul> + {{ $data := .Data }} + {{ range $key, $value := .Data.Terms.Alphabetical }} + <li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li> + {{ end }} + </ul> + </div> + </section> + {{ partial "footer.html" }} + +## Example indexes.html file (ordered) + + {{ partial "header.html" . }} + {{ partial "subheader.html" . }} + + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + <ul> + {{ $data := .Data }} + {{ range $key, $value := .Data.Terms.ByCount }} + <li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li> + {{ end }} + </ul> + </div> + </section> + + {{ partial "footer.html" }} + diff --git a/content/templates/variables.md b/content/templates/variables.md new file mode 100644 index 0000000..f7a202b --- /dev/null +++ b/content/templates/variables.md @@ -0,0 +1,82 @@ +--- +aliases: +- /doc/variables/ +- /layout/variables/ +date: 2013-07-01 +linktitle: Variables +menu: + main: + parent: layout +next: /templates/content +prev: /templates/functions +title: Template Variables +weight: 20 +--- + +Hugo makes a set of values available to the templates. Go templates are context based. The following +are available in the context for the templates. + +## Page Variables + +The following is a list of most of the accessible variables which can be +defined for a piece of content. Many of these will be defined in the front +matter, content or derived from file location. + +**.Title** The title for the content.<br> +**.Content** The content itself, defined below the front matter.<br> +**.Summary** A generated summary of the content for easily showing a snippet in a summary view. Note that the breakpoint can be set manually by inserting *<!--more-->* at the appropriate place in the content page.<br> +**.Description** The description for the content.<br> +**.Keywords** The meta keywords for this content.<br> +**.Date** The date the content is associated with.<br> +**.PublishDate** The date the content is published on.<br> +**.Type** The content [type](/content/types/) (e.g. post)<br> +**.Section** The [section](/content/sections/) this content belongs to<br> +**.Permalink** The Permanent link for this page.<br> +**.RelPermalink** The Relative permanent link for this page.<br> +**.LinkTitle** Access when creating links to this content. Will use linktitle if set in front-matter, else title<br> +**.Taxonomies** These will use the field name of the plural form of the index (see tags and categories above)<br> +**.RSSLink** Link to the indexes' rss link <br> +**.TableOfContents** The rendered table of contents for this content<br> +**.Prev** Pointer to the previous content (based on pub date)<br> +**.Next** Pointer to the following content (based on pub date)<br> +**.FuzzyWordCount** The approximate number of words in the content.<br> +**.WordCount** The number of words in the content.<br> +**.ReadingTime** The estimated time it takes to read the content in minutes.<br> +**.Weight** Assigned weight (in the front matter) to this content, used in sorting.<br> +**.IsNode** Always false for pages.<br> +**.IsPage** Always true for page.<br> +**.Site** See site variables below<br> + +## Page Params + +Any other value defined in the front matter, including indexes will be made available under `.Params`. +Take for example I'm using tags and categories as my indexes. The following would be how I would access them: + +**.Params.tags** <br> +**.Params.categories** <br> +<br> +**All Params are only accessible using all lowercase characters**<br> + +## Node Variables +In Hugo a node is any page not rendered directly by a content file. This +includes indexes, lists and the homepage. + +**.Title** The title for the content.<br> +**.Date** The date the content is published on.<br> +**.Permalink** The Permanent link for this node<br> +**.Url** The relative url for this node.<br> +**.RSSLink** Link to the indexes' rss link <br> +**.Data** The data specific to this type of node.<br> +**.IsNode** Always true for nodes.<br> +**.IsPage** Always false for nodes.<br> +**.Site** See site variables below<br> + +## Site Variables + +Also available is `.Site` which has the following: + +**.Site.BaseUrl** The base URL for the site as defined in the config.json file.<br> +**.Site.Taxonomies** The indexes for the entire site.<br> +**.Site.LastChange** The date of the last change of the most recent content.<br> +**.Site.Recent** Array of all content ordered by Date, newest first.<br> +**.Site.Params** A container holding the values from `params` in your site configuration file.<br> diff --git a/content/templates/views.md b/content/templates/views.md new file mode 100644 index 0000000..82817e8 --- /dev/null +++ b/content/templates/views.md @@ -0,0 +1,127 @@ +--- +aliases: +- /templates/views/ +date: 2013-07-01 +menu: + main: + parent: layout +next: /templates/partials +prev: /templates/terms +title: Content Views +weight: 70 +--- + +In addition to the [single content template](/templates/content/), Hugo can render alternative views of +your content. These are especially useful in [list templates](/templates/list). + +For example you may want content of every type to be shown on the +homepage, but only a summary view of it there. Perhaps on a taxonomy +list page you would only want a bulleted list of your content. Views +make this very straightforward by delegating the rendering of each +different type of content to the content itself. + + +## Creating a content view + +To create a new view simple create a template in each of your different +content type directories with the view name. In the following example we +have created a "li" view and a "summary" view for our two content types +of post and project. As you can see these sit next to the [single +content view](/templates/content) template "single.html". You can even +provide a specific view for a given type and continue to use the +\_default/single.html for the primary view. + + ▾ layouts/ + ▾ post/ + li.html + single.html + summary.html + ▾ project/ + li.html + single.html + summary.html + +Hugo also has support for a default content template to be used in the event +that a specific template has not been provided for that type. The default type +works the same as the other types, but the directory must be called "_default". +Content views can also be defined in the "_default" directory. + + + ▾ layouts/ + ▾ _default/ + li.html + single.html + summary.html + + +## Which Template will be rendered? +Hugo uses a set of rules to figure out which template to use when +rendering a specific page. + +Hugo will use the following prioritized list. If a file isn’t present, +then the next one in the list will be used. This enables you to craft +specific layouts when you want to without creating more templates +than necessary. For most sites only the \_default file at the end of +the list will be needed. + +* /layouts/`TYPE`/`VIEW`.html +* /layouts/\_default/`VIEW`.html +* /themes/`THEME`/layouts/`TYPE`/`VIEW`.html +* /themes/`THEME`/layouts/\_default/`view`.html + + +## Example using views + +### rendering view inside of a list + +Using the summary view (defined below) inside of a ([list +templates](/templates/list)). + + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + </div> + </section> + +In the above example you will notice that we have called .Render and passed in +which view to render the content with. Render is a special function available on +a content which tells the content to render itself with the provided view template. +In this example we are not using the li view. To use this we would +change the render line to `{{ .Render "li" }}`. + + +### li.html + +Hugo will pass the entire page object to the view template. See [page +variables](/templates/variables) for a complete list. + +This content template is used for [spf13.com](http://spf13.com). + + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + +### summary.html + +Hugo will pass the entire page object to the view template. See [page +variables](/templates/variables) for a complete list. + +This content template is used for [spf13.com](http://spf13.com). + + <article class="post"> + <header> + <h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2> + <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div> + </header> + + {{ .Summary }} + <footer> + <a href='{{ .Permalink }}'><nobr>Read more →</nobr></a> + </footer> + </article> + + |