From 667e11c4ec3835d959aab1797647bd0a49869674 Mon Sep 17 00:00:00 2001 From: etienne Date: Tue, 21 Oct 2014 23:35:24 +0200 Subject: Init commit --- content/templates/404.md | 41 +++++ content/templates/content.md | 161 ++++++++++++++++ content/templates/functions.md | 164 +++++++++++++++++ content/templates/go-templates.md | 379 ++++++++++++++++++++++++++++++++++++++ content/templates/homepage.md | 78 ++++++++ content/templates/list.md | 338 +++++++++++++++++++++++++++++++++ content/templates/overview.md | 72 ++++++++ content/templates/partials.md | 103 +++++++++++ content/templates/rss.md | 100 ++++++++++ content/templates/sitemap.md | 52 ++++++ content/templates/terms.md | 160 ++++++++++++++++ content/templates/variables.md | 82 +++++++++ content/templates/views.md | 127 +++++++++++++ 13 files changed, 1857 insertions(+) create mode 100644 content/templates/404.md create mode 100644 content/templates/content.md create mode 100644 content/templates/functions.md create mode 100644 content/templates/go-templates.md create mode 100644 content/templates/homepage.md create mode 100644 content/templates/list.md create mode 100644 content/templates/overview.md create mode 100644 content/templates/partials.md create mode 100644 content/templates/rss.md create mode 100644 content/templates/sitemap.md create mode 100644 content/templates/terms.md create mode 100644 content/templates/variables.md create mode 100644 content/templates/views.md (limited to 'content/templates') 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" . }} + +

+ + {{ 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 }} + +

+ {{ .Content }} +

+ + + + {{ 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 }} + +

+ {{ .Content }} +

+ + + + {{if isset .Params "project_url" }} +

+ Fork me on GitHub +

+ {{ 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. +

{{ $page.Title }}

+ + +## 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 }} + +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" }}

{{ 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 }}

{{ 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: + + {{ "" | 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 }} +

{{ . }} - {{ $title }}

+ {{ 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 }} +

+ {{ .TableOfContents }} +

+ {{ 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 `

{{ .Title }}

{{ .Title }}

{{ .Title }}

{{ index .Params "title" }}

{{ . }}