hugo/docs/content/templates/partials.md

---
aliases:
- /layout/chrome/
date: 2013-07-01
menu:
  main:
    parent: layout
next: /templates/rss
prev: /templates/views
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 /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.

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

By ensuring that we only reference [variables](/layout/variables/)
used for both nodes and pages, we can use the same partials for both.

## 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. `/layout/partials/post/tag/list.html`, call it this way:

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

Note that the subdirectories you create under /layout/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 paramters.

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 the partial _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`
-												Complete overhaul of the docs

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

											
										
										
											2014-05-29 18:42:05 -04:00
+								aliases:
 								- /layout/chrome/
 								date: 2013-07-01
-												Implementing new menu system in the docs site

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

											
										
										
											2014-05-29 18:42:05 -04:00
+								    parent: layout
 								next: /templates/rss
 								prev: /templates/views
 								title: Partial Templates
 								weight: 80
-												docs: add ToC to some more pages

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

											
										
										
											2013-08-17 08:34:25 -04: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 00:12:26 -04: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-29 23:42:26 -04:00
+								partial template that can be included anywhere. As you create the rest of your
-												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-26 21:34:09 -04:00
+								templates, you will include templates from the /layout/partials directory, or from arbitrary subdirectories like /layout/partials/post/tag.
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 16:15:19 -04: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 00:12:26 -04: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 16:15:19 -04: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 08:34:25 -04:00
-												Updating / Rewriting / Adding all of the documentation in preparation for the next release

											
										
										
											2014-05-27 18:32:57 -04: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 08:34:25 -04:00
 								    ▾ layouts/
-												Updating / Rewriting / Adding all of the documentation in preparation for the next release

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

											
										
										
											2013-08-17 08:34:25 -04:00
+								          header.html
 								          footer.html
-												Updating / Rewriting / Adding all of the documentation in preparation for the next release

											
										
										
											2014-05-27 18:32:57 -04:00
+								By ensuring that we only reference [variables](/layout/variables/)
-												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 00:12:26 -04:00
+								used for both nodes and pages, we can use the same partials for both.
-												Complete overhaul of the docs

											
										
										
											2013-08-17 08:34:25 -04:00
-												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 14:00:08 -04:00
+								## Partial vs Template
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 16:15:19 -04: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 00:12:26 -04: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 16:15:19 -04: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 00:12:26 -04: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-29 23:42:26 -04: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 16:15:19 -04: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 00:12:26 -04:00
+								With the addition of the theme system in v0.11, it became apparent that a theme
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

											
										
										
											2014-06-06 16:15:19 -04:00
+								& override aware partial was needed.
-												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 00:12:26 -04: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 16:15:19 -04: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 00:12:26 -04: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-27 21:17:09 -05:00
+								This header template is used for [spf13.com](http://spf13.com/):
-												Complete overhaul of the docs

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

											
										
										
											2014-05-15 09:58:55 -04: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 08:34:25 -04:00
-												Adding 'partial' template function to add theme / local awareness to the partials directory.

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

											
										
										
											2013-08-17 08:34:25 -04: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 02:44:12 -04:00
+								        <base href="{{ .Site.BaseURL }}">
-												Switching docs highlighting to highlight.js .. Docs build super fast again!

											
										
										
											2014-05-15 09:58:55 -04:00
+								        <title> {{ .Title }} : spf13.com </title>
 								        <link rel="canonical" href="{{ .Permalink }}">
 								        {{ if .RSSlink }}<link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
-												Complete overhaul of the docs

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

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

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

											
										
										
											2013-08-17 08:34:25 -04: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 00:12:26 -04: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-27 21:17:09 -05:00
+								This footer template is used for [spf13.com](http://spf13.com/):
-												Complete overhaul of the docs

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

											
										
										
											2014-05-15 09:58:55 -04: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 00:12:26 -04: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 14:00:08 -04: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 09:58:55 -04: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 14:00:08 -04:00
+								        ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
-												Switching docs highlighting to highlight.js .. Docs build super fast again!

											
										
										
											2014-05-15 09:58:55 -04: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 08:34:25 -04:00
-												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 14:00:08 -04:00
+								To reference a partial template stored in a subfolder, e.g. `/layout/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-26 21:34:09 -04:00
 								     {{ partial "post/tag/list" . }}
-												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 14:00:08 -04:00
+								Note that the subdirectories you create under /layout/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-26 21:34:09 -04:00
-												Added documentation about variable scoping in "partials".

											
										
										
											2016-01-01 16:08:39 -05:00
+								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 paramters.
 . 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.
 								This means the partial _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`