docs: Document partialCached func

Fixes #2779

docs/content/templates/functions.md

@@ -1011,15 +1011,19 @@ responses of APIs.
 
 The response of the GitHub API contains the base64-encoded version of the [README.md](https://github.com/spf13/hugo/blob/master/README.md) in the Hugo repository. Now we can decode it and parse the Markdown. The final output will look similar to the rendered version on GitHub.
 
+***
+
+### partialCached
+
+See [Template Partials]({{< relref "templates/partials.md#cached-partials" >}}) for an explanation of the `partialCached` template function.
+
 
 ## .Site.GetPage
 Every `Page` has a `Kind` attribute that shows what kind of page it is. While this attribute can be used to list pages of a certain `kind` using `where`, often it can be useful to fetch a single page by its path.
 
 `GetPage` looks up an index page of a given `Kind` and `path`. This method may support regular pages in the future, but currently it is a convenient way of getting the index pages, such as the home page or a section, from a template:
 
-```
+    {{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}
- {{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}
- ```
 
 This method wil return `nil` when no page could be found, so the above will not print anything if the blog section isn't found.
 

docs/content/templates/partials.md

@@ -15,7 +15,8 @@ toc: true
 
 In practice, it's very convenient to split out common template portions into a
 partial template that can be included anywhere. As you create the rest of your
-templates, you will include templates from the /layout/partials directory, or from arbitrary subdirectories like /layout/partials/post/tag.
+templates, you will include templates from the ``/layout/partials` directory
+or from arbitrary subdirectories like `/layout/partials/post/tag`.
 
 Partials are especially important for themes as it gives users an opportunity
 to overwrite just a small part of your theme, while maintaining future compatibility.
@@ -43,7 +44,7 @@ you could include a partial template with the `template` call in the standard
 template language.
 
 With the addition of the theme system in v0.11, it became apparent that a theme
-& override aware partial was needed.
+& override-aware partial was needed.
 
 When using Hugo v0.12 and above, please use the `partial` call (and leave out
 the “partial/” path). The old approach would still work, but wouldn’t benefit from
@@ -110,8 +111,7 @@ For more examples of referencing these templates, see
 [homepage templates](/templates/homepage/).
 
 
-Variable scoping
+## Variable scoping
-----------------
 
 As you might have noticed, `partial` calls receive two parameters.
 
@@ -122,3 +122,25 @@ location to be read.
 This means that the partial will _only_ be able to access those variables. It is
 isolated and has no access to the outer scope. From within the
 partial, `$.Var` is equivalent to `.Var`
+
+## Cached Partials
+
+The `partialCached` template function can offer significant performance gains
+for complex templates that don't need to be rerendered upon every invocation.
+The simplest usage is as follows:
+
+    {{ partialCached "footer.html" . }}
+
+You can also pass additional parameters to `partialCached` to create *variants* of the cached partial.
+For example, say 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:
+
+    {{ partialCached "footer.html" . .Section }}
+
+If you need to pass additional parameters to create unique variants,
+you can pass as many variant parameters as you need:
+
+    {{ partialCached "footer.html" . .Params.country .Params.province }}
+
+Note that the variant parameters are not made available to the underlying partial template.
+They are only use to create a unique cache key.