shithub: hugo

--- a/docs/content/templates/functions.md

+++ b/docs/content/templates/functions.md

@@ -1011,15 +1011,19 @@

 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.

--- a/docs/content/templates/partials.md

+++ b/docs/content/templates/partials.md

@@ -15,7 +15,8 @@

 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 @@

 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,9 +111,8 @@

 [homepage templates](/templates/homepage/).

-Variable scoping

-----------------

+## Variable scoping

 As you might have noticed, `partial` calls receive two parameters.

 1. The first is the name of the partial and determines the file

@@ -122,3 +122,25 @@

 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.