From 7d7b1f03c1668f45b29705ad44770d795e45a1ec Mon Sep 17 00:00:00 2001
From: Regis Philibert <login@regisphilibert.com>
Date: Wed, 17 Apr 2019 17:31:35 -0400
Subject: [PATCH] Document partials returning a value.

---
 content/en/templates/partials.md | 40 ++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/content/en/templates/partials.md b/content/en/templates/partials.md
index c7b35222c..bf183d8b8 100644
--- a/content/en/templates/partials.md
+++ b/content/en/templates/partials.md
@@ -77,6 +77,46 @@ The second argument in a partial call is the variable being passed down. The abo
 
 This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`.
 
+### Returning a value
+
+In addition to outputting markup, partials can be used to return a value of any type. In order to return a value, a partial must include a lone `return` statement.
+
+#### Example GetFeatured
+```go-html-template
+{{/* layouts/partials/GetFeatured.html */}}
+{{ return first . (where site.RegularPages ".Params.featured" true) }}
+```
+
+```go-html-template
+{{/* layouts/index.html */}}
+{{ range partial "GetFeatured.html" 5 }}
+  [...]
+{{ end }}
+```
+#### Example GetImage
+```go-html-template
+{{/* layouts/partials/GetImage.html */}}
+{{ $return := false }}
+{{ with .Params.gallery }}
+  {{ $return = index . 0 }}
+{{ end }}
+{{ with .Params.image }}
+  {{ $return = . }}
+{{ end }}
+{{ return $return }}
+```
+
+```go-html-template
+{{/* layouts/_default/single.html */}}
+{{ with partial "GetImage.html" . }}
+  [...]
+{{ end }}
+```
+
+{{% note %}}
+Only one `return` statement is allowed per partial file.
+{{% /note %}}
+
 ### Cached Partials
 
 The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows: