hugo/docs/content/templates/partials.md

---
aliases:
- /layout/chrome/
lastmod: 2016-01-01
date: 2013-07-01
menu:
  main:
    parent: layout
next: /templates/rss
prev: /templates/blocks/
title: Partial Templates
weight: 80
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 ``/layouts/partials` directory
or from arbitrary subdirectories like `/layouts/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.

Theme developers may want to include a few partials with empty HTML
files in the theme just so end users have an easy place to inject their
customized content.

I've found it helpful to include a header and footer template in
partials so I can include those in all the full page layouts.  There is
nothing special about header.html and footer.html other than they seem
like good names to use for inclusion in your other templates.

    ▾ layouts/
      ▾ partials/
          header.html
          footer.html

## Partial vs Template

Version v0.12 of Hugo introduced the `partial` call inside the template system.
This is a change to the way partials were handled previously inside the
template system. In earlier versions, Hugo didn’t treat partials specially, and
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.

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
the ability to have users override the partial theme file with local layouts.

## Example header.html
This header template is used for [spf13.com](http://spf13.com/):

    <!DOCTYPE html>
    <html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
    <head>
        <meta charset="utf-8">

        {{ partial "meta.html" . }}

        <base href="{{ .Site.BaseURL }}">
        <title> {{ .Title }} : spf13.com </title>
        <link rel="canonical" href="{{ .Permalink }}">
        {{ if .RSSLink }}<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}

        {{ partial "head_includes.html" . }}
    </head>
    <body lang="en">

## Example footer.html
This footer template is used for [spf13.com](http://spf13.com/):

    <footer>
      <div>
        <p>
        &copy; 2013-14 Steve Francia.
        <a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>;
        please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>.
        </p>
      </div>
    </footer>
    <script type="text/javascript">

      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-XYSYXYSY-X']);
      _gaq.push(['_trackPageview']);

      (function() {
        var ga = document.createElement('script');
        ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
            'http://www') + '.google-analytics.com/ga.js';
        ga.setAttribute('async', 'true');
        document.documentElement.firstChild.appendChild(ga);
      })();

    </script>
    </body>
    </html>

To reference a partial template stored in a subfolder, e.g. `/layouts/partials/post/tag/list.html`, call it this way:

     {{ partial "post/tag/list" . }}

Note that the subdirectories you create under /layouts/partials can be named whatever you like.

For more examples of referencing these templates, see
[single content templates](/templates/content/),
[list templates](/templates/list/) and
[homepage templates](/templates/homepage/).


## 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
location to be read.
2. The second is the variables to be passed down to the partial.

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.
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
+								---
-												Converting front matter to YAML

											
										
										
											2014-05-29 22:42:05 +00:00
+								aliases:
 								- /layout/chrome/
-												docs: Add lastmod to content files

Based on last commit in Git.

											
										
										
											2016-01-06 22:45:19 +00:00
+								lastmod: 2016-01-01
-												Converting front matter to YAML

											
										
										
											2014-05-29 22:42:05 +00:00
+								date: 2013-07-01
-												Implementing new menu system in the docs site

											
										
										
											2014-04-23 07:00:11 +00:00
+								menu:
 								  main:
-												Converting front matter to YAML

											
										
										
											2014-05-29 22:42:05 +00:00
+								    parent: layout
 								next: /templates/rss
-												docs: Document Go 1.6's new ability to trim whitespace

											
										
										
											2016-04-02 15:34:04 +00:00
+								prev: /templates/blocks/
-												Converting front matter to YAML

											
										
										
											2014-05-29 22:42:05 +00:00
+								title: Partial Templates
 								weight: 80
-												docs: add ToC to some more pages

											
										
										
											2015-05-22 18:46:09 +00:00
+								toc: true
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
+								---
-												More proofreading and minor revisions to Hugo docs

Among the various changes, most instances of

    {{ template "partials/FILE.html" . }}

were changed to

    {{ partial "FILE.html" . }}

Also, in main.go, change "2013" to "2013-14".

											
										
										
											2014-09-03 04:12:26 +00:00
+								In practice, it's very convenient to split out common template portions into a
-												Adding a page listing the different methods available to Taxonomies.

											
										
										
											2014-08-30 03:42:26 +00:00
+								partial template that can be included anywhere. As you create the rest of your
-												docs: Update layouts path name


											
										
										
											2016-12-16 00:09:51 +00:00
+								templates, you will include templates from the ``/layouts/partials` directory
 								or from arbitrary subdirectories like `/layouts/partials/post/tag`.
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 20:15:19 +00:00
 								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.
-												More proofreading and minor revisions to Hugo docs

Among the various changes, most instances of

    {{ template "partials/FILE.html" . }}

were changed to

    {{ partial "FILE.html" . }}

Also, in main.go, change "2013" to "2013-14".

											
										
										
											2014-09-03 04:12:26 +00:00
+								Theme developers may want to include a few partials with empty HTML
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 20:15:19 +00:00
+								files in the theme just so end users have an easy place to inject their
 								customized content.
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
-												Updating / Rewriting / Adding all of the documentation in preparation for the next release

											
										
										
											2014-05-27 22:32:57 +00:00
+								I've found it helpful to include a header and footer template in
 								partials so I can include those in all the full page layouts.  There is
 								nothing special about header.html and footer.html other than they seem
 								like good names to use for inclusion in your other templates.
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
 								    ▾ layouts/
-												Updating / Rewriting / Adding all of the documentation in preparation for the next release

											
										
										
											2014-05-27 22:32:57 +00:00
+								      ▾ partials/
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
+								          header.html
 								          footer.html
-												doc: Strip trailing whitespace; other revisions

Make some random and non-comprehensive changes to the
template functions documentation to make them more
consistent.

											
										
										
											2015-08-04 18:00:08 +00:00
+								## Partial vs Template
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 20:15:19 +00:00
-												More proofreading and minor revisions to Hugo docs

Among the various changes, most instances of

    {{ template "partials/FILE.html" . }}

were changed to

    {{ partial "FILE.html" . }}

Also, in main.go, change "2013" to "2013-14".

											
										
										
											2014-09-03 04:12:26 +00:00
+								Version v0.12 of Hugo introduced the `partial` call inside the template system.
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 20:15:19 +00:00
+								This is a change to the way partials were handled previously inside the
-												More proofreading and minor revisions to Hugo docs

Among the various changes, most instances of

    {{ template "partials/FILE.html" . }}

were changed to

    {{ partial "FILE.html" . }}

Also, in main.go, change "2013" to "2013-14".

											
										
										
											2014-09-03 04:12:26 +00:00
+								template system. In earlier versions, Hugo didn’t treat partials specially, and
-												Adding a page listing the different methods available to Taxonomies.

											
										
										
											2014-08-30 03:42:26 +00:00
+								you could include a partial template with the `template` call in the standard
 								template language.
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 20:15:19 +00:00
-												More proofreading and minor revisions to Hugo docs

Among the various changes, most instances of

    {{ template "partials/FILE.html" . }}

were changed to

    {{ partial "FILE.html" . }}

Also, in main.go, change "2013" to "2013-14".

											
										
										
											2014-09-03 04:12:26 +00:00
+								With the addition of the theme system in v0.11, it became apparent that a theme
-												docs: Document partialCached func

Fixes #2779

											
										
										
											2016-12-14 02:37:34 +00:00
+								& override-aware partial was needed.
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 20:15:19 +00:00
-												More proofreading and minor revisions to Hugo docs

Among the various changes, most instances of

    {{ template "partials/FILE.html" . }}

were changed to

    {{ partial "FILE.html" . }}

Also, in main.go, change "2013" to "2013-14".

											
										
										
											2014-09-03 04:12:26 +00:00
+								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
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 20:15:19 +00:00
+								the ability to have users override the partial theme file with local layouts.
-												More proofreading and minor revisions to Hugo docs

Among the various changes, most instances of

    {{ template "partials/FILE.html" . }}

were changed to

    {{ partial "FILE.html" . }}

Also, in main.go, change "2013" to "2013-14".

											
										
										
											2014-09-03 04:12:26 +00:00
+								## Example header.html
-												[Docs] Copyediting

 * Add meta author, description and generator tags
 * Add Hugo version beside the logo and in the footer
 * Suggest the user to run `go get -u -v` to update dependencies
 * Requires Go 1.3+ rather than Go 1.1+
 * Improve rendering/formatting in some places
 * Add trailing slash to URLs where appropriate
 * GitHub redirects all http requests to https, update accordingly

											
										
										
											2015-01-28 02:17:09 +00:00
+								This header template is used for [spf13.com](http://spf13.com/):
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
-												Switching docs highlighting to highlight.js .. Docs build super fast again!

											
										
										
											2014-05-15 13:58:55 +00:00
+								    <!DOCTYPE html>
 								    <html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
 								    <head>
 								        <meta charset="utf-8">
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 20:15:19 +00:00
+								        {{ partial "meta.html" . }}
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
-												Update Hugo docs with the initialisms suggested by golint

In particular:

 * .Url → .URL (for node, menu and paginator)
 * .Site.BaseUrl → .Site.BaseURL
 * getJson → getJSON
 * getCsv → getCSV
 * safeHtml → safeHTML
 * safeCss → safeCSS
 * safeUrl → safeURL

Continued effort in fixing #959.

											
										
										
											2015-03-18 06:44:12 +00:00
+								        <base href="{{ .Site.BaseURL }}">
-												Switching docs highlighting to highlight.js .. Docs build super fast again!

											
										
										
											2014-05-15 13:58:55 +00:00
+								        <title> {{ .Title }} : spf13.com </title>
 								        <link rel="canonical" href="{{ .Permalink }}">
-												docs: Rename RSSlink to RSSLink

The former will be deprecated.

											
										
										
											2016-11-17 07:18:55 +00:00
+								        {{ if .RSSLink }}<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 20:15:19 +00:00
+								        {{ partial "head_includes.html" . }}
-												Switching docs highlighting to highlight.js .. Docs build super fast again!

											
										
										
											2014-05-15 13:58:55 +00:00
+								    </head>
 								    <body lang="en">
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
-												More proofreading and minor revisions to Hugo docs

Among the various changes, most instances of

    {{ template "partials/FILE.html" . }}

were changed to

    {{ partial "FILE.html" . }}

Also, in main.go, change "2013" to "2013-14".

											
										
										
											2014-09-03 04:12:26 +00:00
+								## Example footer.html
-												[Docs] Copyediting

 * Add meta author, description and generator tags
 * Add Hugo version beside the logo and in the footer
 * Suggest the user to run `go get -u -v` to update dependencies
 * Requires Go 1.3+ rather than Go 1.1+
 * Improve rendering/formatting in some places
 * Add trailing slash to URLs where appropriate
 * GitHub redirects all http requests to https, update accordingly

											
										
										
											2015-01-28 02:17:09 +00:00
+								This footer template is used for [spf13.com](http://spf13.com/):
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
-												Switching docs highlighting to highlight.js .. Docs build super fast again!

											
										
										
											2014-05-15 13:58:55 +00:00
+								    <footer>
 								      <div>
 								        <p>
-												More proofreading and minor revisions to Hugo docs

Among the various changes, most instances of

    {{ template "partials/FILE.html" . }}

were changed to

    {{ partial "FILE.html" . }}

Also, in main.go, change "2013" to "2013-14".

											
										
										
											2014-09-03 04:12:26 +00:00
+								        &copy; 2013-14 Steve Francia.
-												doc: Strip trailing whitespace; other revisions

Make some random and non-comprehensive changes to the
template functions documentation to make them more
consistent.

											
										
										
											2015-08-04 18:00:08 +00:00
+								        <a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>;
-												Switching docs highlighting to highlight.js .. Docs build super fast again!

											
										
										
											2014-05-15 13:58:55 +00:00
+								        please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>.
 								        </p>
 								      </div>
 								    </footer>
 								    <script type="text/javascript">
 								      var _gaq = _gaq || [];
 								      _gaq.push(['_setAccount', 'UA-XYSYXYSY-X']);
 								      _gaq.push(['_trackPageview']);
 								      (function() {
 								        var ga = document.createElement('script');
-												doc: Strip trailing whitespace; other revisions

Make some random and non-comprehensive changes to the
template functions documentation to make them more
consistent.

											
										
										
											2015-08-04 18:00:08 +00:00
+								        ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
-												Switching docs highlighting to highlight.js .. Docs build super fast again!

											
										
										
											2014-05-15 13:58:55 +00:00
+								            'http://www') + '.google-analytics.com/ga.js';
 								        ga.setAttribute('async', 'true');
 								        document.documentElement.firstChild.appendChild(ga);
 								      })();
 								    </script>
 								    </body>
 								    </html>
-												Complete overhaul of the docs

											
										
										
											2013-08-17 12:34:25 +00:00
-												docs: Update layouts path name


											
										
										
											2016-12-16 00:09:51 +00:00
+								To reference a partial template stored in a subfolder, e.g. `/layouts/partials/post/tag/list.html`, call it this way:
-												Clarify partials folder subfolders

A couple of edits to clarify that the layout/partials folder can contain arbitrarily-named subfolders, since I found the examples using ``{{ partial "post/tag/list" . }}`` confusing. Some folders are named specifically to work a certain way with hugo, but although the examples use key functional section and taxonomy names like post and tag, it does not matter what they are called. Hopefully this will help other newbs.

											
										
										
											2015-04-27 01:34:09 +00:00
 								     {{ partial "post/tag/list" . }}
-												docs: Update layouts path name


											
										
										
											2016-12-16 00:09:51 +00:00
+								Note that the subdirectories you create under /layouts/partials can be named whatever you like.
-												Clarify partials folder subfolders

A couple of edits to clarify that the layout/partials folder can contain arbitrarily-named subfolders, since I found the examples using ``{{ partial "post/tag/list" . }}`` confusing. Some folders are named specifically to work a certain way with hugo, but although the examples use key functional section and taxonomy names like post and tag, it does not matter what they are called. Hopefully this will help other newbs.

											
										
										
											2015-04-27 01:34:09 +00:00
-												Added documentation about variable scoping in "partials".

											
										
										
											2016-01-01 21:08:39 +00:00
+								For more examples of referencing these templates, see
 								[single content templates](/templates/content/),
 								[list templates](/templates/list/) and
 								[homepage templates](/templates/homepage/).
-												docs: Document partialCached func

Fixes #2779

											
										
										
											2016-12-14 02:37:34 +00:00
+								## Variable scoping
-												Added documentation about variable scoping in "partials".

											
										
										
											2016-01-01 21:08:39 +00:00
-												docs: Correct spelling for "parameters" in partials.md

											
										
										
											2016-08-28 13:21:19 +00:00
+								As you might have noticed, `partial` calls receive two parameters.
-												Added documentation about variable scoping in "partials".

											
										
										
											2016-01-01 21:08:39 +00:00
 . The first is the name of the partial and determines the file
 								location to be read.
 . The second is the variables to be passed down to the partial.
-												docs: Fix grammar in templates/partials.md

Noticed this sentence seemingly missing a word or two.

											
										
										
											2016-04-15 03:05:24 +00:00
+								This means that the partial will _only_ be able to access those variables. It is
-												Added documentation about variable scoping in "partials".

											
										
										
											2016-01-01 21:08:39 +00:00
+								isolated and has no access to the outer scope. From within the
 								partial, `$.Var` is equivalent to `.Var`
-												docs: Document partialCached func

Fixes #2779

											
										
										
											2016-12-14 02:37:34 +00:00
 								## 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.