Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

docs/content/en/functions/partials/Include.md

@@ -1,22 +1,24 @@
 ---
 title: partials.Include
-linkTitle: partial
-description: Executes the named partial template. If the partial contains a return statement, returns that value, else returns the rendered output.
-categories: [functions]
+description: Executes the given partial template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: [partial]
+  related:
+    - functions/go-template/return
+    - functions/partials/IncludeCached
+    - functions/go-template/template
+    - methods/page/Render
   returnType: any
-  signatures: ['partials.Include LAYOUT [CONTEXT]']
-relatedFunctions:
-  - partials.Include
-  - partials.IncludeCached
+  signatures: ['partials.Include NAME [CONTEXT]']
 aliases: [/functions/partial]
 ---
 
+Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type.
+
+[`return`]: /functions/go-template/return
+
 In this example we have three partial templates:
 
 ```text
@@ -63,5 +65,21 @@ Then, within the partial template:
 <p>{{ .name }} is majoring in {{ .major }}. Their grade point average is {{ .gpa }}.</p>
 ```
 
+To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
+
+```go-html-template
+{{ $result := false }}
+{{ if math.ModBool . 2 }}
+  {{ $result = "even" }}
+{{ else }}
+  {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+```
+
+See&nbsp;[details][`return`].
+
+[`return`]: /functions/go-template/return
 
 [breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants
+[details]: /functions/go-template/return

docs/content/en/functions/partials/IncludeCached.md

@@ -1,30 +1,32 @@
 ---
 title: partials.IncludeCached
-linkTitle: partialCached
-description: Allows for caching of partials that do not need to be re-rendered on every invocation.
-categories: [functions]
+description: Executes the given template and caches the result, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: functions
-function:
+action:
   aliases: [partialCached]
+  related:
+    - functions/go-template/return
+    - functions/partials/Include
+    - functions/go-template/template
+    - methods/page/Render
   returnType: any
   signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]']
-relatedFunctions:
-  - partials.Include
-  - partials.IncludeCached
 signatures: 
-  - partials.IncludeCached LAYOUT CONTEXT [VARIANT...]
-  - partialCached LAYOUT CONTEXT [VARIANT...]
+  - partials.IncludeCached NAME CONTEXT [VARIANT...]
+  - partialCached NAME CONTEXT [VARIANT...]
 aliases: [/functions/partialcached]
 ---
 
-The `partialCached` template function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation.
+Without a [`return`] statement, the `partialCached` function returns a string of type `template.HTML`. With a `return` statement, the `partialCached` function can return any data type.
 
-**Note:** Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once.
+The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation.
 
-**Note**: Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result.
+{{% note %}}
+Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once.
+
+Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result.
+{{% /note %}}
 
 Here is the simplest usage:
 
@@ -32,18 +34,32 @@ Here is the simplest usage:
 {{ partialCached "footer.html" . }}
 ```
 
-You can also pass additional arguments to `partialCached` to create *variants* of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, you could use a variant based upon section so that the partial is only rendered once per section:
+Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section:
 
-{{< code file="partial-cached-example.html" >}}
+{{< code file=partial-cached-example.html >}}
 {{ partialCached "footer.html" . .Section }}
 {{< /code >}}
 
-If you need to pass additional arguments to create unique variants, you can pass as many variant arguments as you need:
+Pass additional arguments, of any data type, as needed to create unique variants:
 
 ```go-html-template
 {{ partialCached "footer.html" . .Params.country .Params.province }}
 ```
 
-Note that the variant arguments are not made available to the underlying partial template. They are only use to create a unique cache key. Since Hugo `0.61.0` you can use any object as cache key(s), not just strings.
+The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys. 
 
-See also [The Full Partial Series Part 1: Caching!](https://regisphilibert.com/blog/2019/12/hugo-partial-series-part-1-caching-with-partialcached/).
+To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
+
+```go-html-template
+{{ $result := false }}
+{{ if math.ModBool . 2 }}
+  {{ $result = "even" }}
+{{ else }}
+  {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+```
+
+See&nbsp;[details][`return`].
+
+[`return`]: /functions/go-template/return

docs/content/en/functions/partials/_index.md

@@ -0,0 +1,12 @@
+---
+title: Partial functions
+linkTitle: partials
+description: Template functions to call partial templates.
+categories: []
+keywords: []
+menu:
+  docs:
+    parent: functions
+---
+
+Use these functions to call partial templates.