diff --git a/content/about/what-is-hugo.md b/content/about/what-is-hugo.md index 255fd185a..c132dd1ea 100644 --- a/content/about/what-is-hugo.md +++ b/content/about/what-is-hugo.md @@ -14,7 +14,7 @@ toc: true Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator][]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors. -Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [Surge][], [Aerobatic][], [Firebase][], [Google Cloud Storage][], [Amazon S3][], [Rackspace][], [Azure][], and [CloudFront][] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP. +Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify][], [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [Surge][], [Aerobatic][], [Firebase][], [Google Cloud Storage][], [Amazon S3][], [Rackspace][], [Azure][], and [CloudFront][] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP. We think of Hugo as the ideal website creation tool. Hugo provides nearly instant build times and the ability to rebuild whenever a change is made, which is invaluable when you are designing websites and creating content. @@ -67,6 +67,7 @@ I wanted to develop a fast and full-featured website framework without any depen [Middleman]: https://middlemanapp.com/ [Nanoc]: http://nanoc.ws/ [Nanoc]: https://nanoc.ws/ +[Netlify]: https://netlify.com [rackspace]: https://www.rackspace.com/cloud/files [static site generator]: /about/benefits/ [Rackspace]: https://www.rackspace.com/cloud/files diff --git a/content/templates/go-templates.md b/content/templates/go-templates.md index 26d2d8a89..8178bdc5d 100644 --- a/content/templates/go-templates.md +++ b/content/templates/go-templates.md @@ -12,20 +12,19 @@ weight: 10 draft: false aliases: [/templates/go-template-primer/,/layouts/go-templates/,/layout/go-templates/] toc: true -wip: true --- Hugo uses the excellent [Go html/template][gohtmltemplate] library, an extremely lightweight engine that provides just the right amount of logic to be able to create any style of static website. If you have used other template systems from different languages or frameworks, you will find a lot of similarities in Go templates. {{% note "Go Deep with the Go Docs" %}} -This document is only designed as a brief primer. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/). +This is only a primer. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/). {{% /note %}} ## Introduction to Go Templates 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. As a positive consequence of this simplicity, Go templates parse very quickly. -A unique characteristic of Go templates is that they are content aware. Variables and content will be sanitized depending on the context of where they are used. +A unique characteristic of Go templates is that they are *content aware*. Variables and content will be sanitized depending on the context of where they are used. ## Basic Syntax @@ -45,13 +44,13 @@ Parameters for functions are separated using spaces. The following example calls #### Methods and Fields are Accessed via dot Notation -Accessing the Page Parameter "bar" +Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. ```golang {{ .Params.bar }} ``` -#### Parentheses can be Used to Group Items Together +#### Parentheses Can be Used to Group Items Together ```golang {{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} @@ -59,16 +58,15 @@ Accessing the Page Parameter "bar" ## Variables -Each Go template has a struct (object) made available to it. In Hugo, each -template is passed page struct. More details are available in the [variables and params section][variablesparams]. +Each Go template has a struct (object) made available to it. In Hugo, each template is passed a page's struct. More details on the structs passed to specific page kinds are in the [variables][] section. -A variable is accessed by referencing the variable name. +A variable is accessed by referencing the variable name inside of a template: ```golang {{ .Title }} ``` -Variables can also be defined and referenced. +Variables can also be defined and referenced: ```golang {{ $address := "123 Main St."}} @@ -77,7 +75,9 @@ Variables can also be defined and referenced. ## Functions -Go template ships with a few functions that provide basic functionality. The Go template system also provides a mechanism for applications to extend the set of available functions. [Hugo template functions][hugofunctions] provide additional functionality we believe us 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. +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 @@ -104,7 +104,7 @@ There are more boolean operators than those listed in the Hugo docs in the [Gola 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. +the `/layout/` directory within Hugo. ### Template and Partial Examples @@ -126,10 +126,10 @@ 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 +a map, array, or slice. The following are different examples of how to use range. -#### Example 1: Using Context** +#### Example 1: Using Context ```golang {{ range array }} @@ -137,7 +137,7 @@ range. {{ end }} ``` -#### Example 2: Declaring Value=>Variable name +#### Example 2: Declaring Value => Variable name ```golang {{range $element := array}} @@ -156,13 +156,13 @@ range. ### Conditionals -`if`, `else`, `with`, `or` & `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: * false * 0 -* any array, slice, map, or string of length zero +* any zero-length array, slice, map, or string #### Example 1: `if` @@ -189,12 +189,14 @@ Go Templates treat the following values as false: #### 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, +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 }} +```golang +{{ with .Params.title }}

{{ . }}

{{ end }} +``` #### Example 5: `if` … `else if` @@ -208,19 +210,20 @@ The first example above could be simplified as: ## 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 only can 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. ### Example 1: `shuffle` +The following two examples are functionally the same: + ```golang {{ shuffle (seq 1 5) }} ``` -is the same as ```golang {{ (seq 1 5) | shuffle }} @@ -228,16 +231,12 @@ is the same as ### 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: + ```golang {{ index .Params "disqus_url" | html }} ``` -Access the page parameter called "disqus_url" and escape the HTML. - -The `index` function is built in to [Go][]. [You can read more about `index` in the Godocs][]. The Godocs have the following to say about`index`: - -> ...returns the result of indexing its first argument by the following arguments. Thus "index x 1 2 3" is, in Go syntax, `x[1][2][3]`. Each indexed item must be a map, slice, or array. - ### Example 3: `or` with `isset` ```golang @@ -251,8 +250,9 @@ Could be rewritten as {{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }} Stuff Here {{ end }} +``` -### Example $: Internet Explorer Conditional Comments +### Example 4: Internet Explorer Conditional Comments 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: @@ -270,20 +270,19 @@ Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional co ## Context (aka "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, however, 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 do one of the following: +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: -### Define a Variable Independent of Context +### 1. Define a Variable Independent of Context The following shows how to define a variable independent of the context. -{{% code file="range-through-tags-w-variable.html" %}} +{{% code file="tags-range-with-page-variable.html" %}} ```html {{ $title := .Site.Title }} -{{ $base := .Site.BaseURL }}