mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
127 lines
4.4 KiB
Markdown
127 lines
4.4 KiB
Markdown
---
|
||
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 /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>
|
||
© 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 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`
|