shithub: hugo

Download patch

ref: 65f9427031ae57c0d78360dbbfe03428fe922b49
parent: e4d328d835119bbc9005ccd76177e80bd52cad3c
author: Erik Ebsen <[email protected]>
date: Sat Apr 2 06:34:04 EDT 2016 

docs: Document Go 1.6's new ability to trim whitespace


--- /dev/null
+++ b/docs/content/templates/blocks.md
@@ -1,0 +1,71 @@
+---
+date: 2016-03-29T21:26:20-05:00
+menu:
+  main:
+    parent: layout
+prev: /templates/views/
+next: /templates/partials/
+title: Block Templates
+weight: 80
+---
+
+Go 1.6 includes a powerful new keyword, `block`. This construct allows you to define the outer shell of your pages in a single "base" template, filling in or overriding portions as necessary.
+
+## Define the base template
+
+Let's define a simple base template, a shell from which all our pages will start. To find a base template, Hugo searches the same paths and file names as it does for [Ace templates]({{< relref "templates/ace.md" >}}), just with files suffixed `.html` rather than `.ace`.
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>{{ block "title" . }}
+      <!-- Blocks may include default content. -->
+      {{ .Site.Title }}
+    {{ end }}</title>
+  </head>
+  <body>
+    <!-- Code that all your templates share, like a header -->
+
+    {{ block "main" . }}
+      <!-- The part of the page that begins to differ between templates -->
+    {{ end }}
+
+    <!-- More shared code, perhaps a footer -->
+  </body>
+</html>
+```
+
+## Overriding the base
+
+Your [default list template]({{< relref "templates/list.md" >}}) (`_default/list.html`) will inherit all of the code defined in the base template. It could then implement its own "main" block from the base template above like so:
+
+```html
+<!-- Note the lack of Go's context "dot" when defining blocks -->
+{{ define "main" }}
+  <h1>Posts</h1>
+  {{ range .Data.Pages }}
+    <article>
+      <h2>{{ .Title }}</h2>
+      {{ .Content }}
+    </article>
+  {{ end }}
+{{ end }}
+```
+
+This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a "title" block so the contents from our base template remain unchanged in lists.
+
+In our [default single template]({{< relref "templates/content.md" >}}) (`_default/single.html`), let's implement both blocks:
+
+```html
+{{ define "title" }}
+  {{ .Title }} &ndash; {{ .Site.Title }}
+{{ end }}
+{{ define "main" }}
+  <h1>{{ .Title }}</h1>
+  {{ .Content }}
+{{ end }}
+```
+
+This overrides both block areas from the base template with code unique to our single template.
--- a/docs/content/templates/go-templates.md
+++ b/docs/content/templates/go-templates.md
@@ -297,6 +297,38 @@
     > You may, of course, recover from this mischief by using `{{ $ := . }}`
     > in a global context to reset `$` to its default value.
 
+## Whitespace
+
+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:
+
+```html
+<div>
+  {{ .Title }}
+</div>
+```
+
+will include the newlines and horizontal tab in its HTML output:
+
+```html
+<div>
+  Hello, World!
+</div>
+```
+
+whereas using
+
+```html
+<div>
+  {{- .Title -}}
+</div>
+```
+
+in that case will output simply `<div>Hello, World!</div>`.
+
+Go considers the following characters as whitespace: space, horizontal tab, carriage return and newline.
+
 # Hugo Parameters
 
 Hugo provides the option of passing values to the template language
--- a/docs/content/templates/partials.md
+++ b/docs/content/templates/partials.md
@@ -7,7 +7,7 @@
   main:
     parent: layout
 next: /templates/rss
-prev: /templates/views
+prev: /templates/blocks/
 title: Partial Templates
 weight: 80
 toc: true
--- a/docs/content/templates/views.md
+++ b/docs/content/templates/views.md
@@ -6,7 +6,7 @@
 menu:
   main:
     parent: layout
-next: /templates/partials
+next: /templates/blocks
 prev: /templates/terms
 title: Content Views
 weight: 70