hugo/content/en/templates/partials.md at 5e078383a787e8b5ec3ba73f05ea4130840afbe2

mirror of https://github.com/gohugoio/hugo.git synced 2024-11-14 20:37:55 -05:00

Bjørn Erik Pedersen eb16165694 Squashed 'docs/' changes from 37095d540..d1cf9adc4

d1cf9adc4 Fix typo
26e10a690 Fix the name and arg mismatch between partial defn and call
2db0e53cd Merge commit '9c36cff15224f6cbd19058ad61311229b7a23c83'
9c36cff15 Squashed 'themes/gohugoioTheme/' changes from 68ddff44..b8202f53
4b021eff8 Update lang.Merge.md
b37af2916 Add title to yaml
a9a281233 Fixed incorrect usage of the code-toggle shortcode
4560a0169 Update Warning for Theme Links (#676)
0305e3c6b Document .File.ContentBaseName
6d30c5aa1 Update configuration.md
158df174a Document .Sites and .Sites.First
0c0f583b8 Add stale config
e2531afd8 Document path template functions
4dd779057 Clarify that partialCached is per site/language
19e5bbe0c Update index.md
44b000857 Add missing dot
a41300cf9 Release 0.52
2d1d92b88 Merge branch 'temp52'
c5925250d releaser: Prepare repository for 0.53-DEV
d000b04a2 releaser: Add release notes to /docs for release of 0.52
4bb983a0a releaser: Bump versions for release of 0.52
36736ca28 tpl: Add "param" shortcode
378677aa6 Add Elasticsearch/bonsai.io to services doc.
4c3fd4fa4 docs: Document inline shortcodes
6c64c374c Whitelist CSS modules from purge
817a872b9 Improve search icon position
cf86ff1c7 Add minification and resource cache clear to build command
fd77e8df3 Update asset dependencies and adopt Hugo Pipes
cdbe97e8c Update render.md
b0e279220 git command to update submodule to latest
a1cb98c12 cache/filecache: Add a :project placeholder
07c1b2b46 cache/filecache: Use time.Duration for maxAge
ffa9b165e Add AND as a title
6e7733b40 Add OR as a sub title to make it easier to find in search
72b6791a1 docs: Document the new file cache
714d3ca91 Fix minification issues
cd1e961da Revert "Add Elasticsearch/bonsai.io to services doc."
15a0cda6e Add Elasticsearch/bonsai.io to services doc.
f931d86de Release 0.51
e2ffe867a Merge branch 'temp51'
423e7f5c8 releaser: Prepare repository for 0.52-DEV
c6f2d6ae1 releaser: Add release notes to /docs for release of 0.51
5bbb556dc releaser: Bump versions for release of 0.51
3b2b172b9 docs: Document shortcode error handling
b8672f3d4 docs: Document symdiff
4bc6071e6 docs: Document complement
d1baab752 docs: Re-generate CLI docs
9ea667e24 Revert "tpl: Update Jsonify to return pretty-print output"
ce5a1403d docs: Regenerate the docs helper
99a1f4a94 Fix note for reserved partial name(starting with -> including).
eba3cbc42 fix accidentally modification on paragraph.
3eebd98c3 Add note for reserved partial name.
40b881cc2 Document templates.Exists
b5c3bcd3b Update multilingual.md
61c59c67e Fix misspelling (#648)
f21d8c4a4 Correct minor typo (#5372)
e967001b9 Release 0.50
685fd6b08 releaser: Prepare repository for 0.51-DEV
f245a9faa releaser: Add release notes to /docs for release of 0.50
4354da30d releaser: Bump versions for release of 0.50
feaa05469 docs: Regenerate CLI docs
5c724200c Merge commit 'd6a4af7018e8618944a6471ceeb7aae1d4df6afa'
2ddab36c2 Merge commit '74309fe5699a595080fdb3a14711e0869babce99'
8cf296a7c docs: Regenerate CLI docs
9097683dd tpl: Update Jsonify to return pretty-print output

git-subtree-dir: docs
git-subtree-split: d1cf9adc412245c96d9d32592a903370d3972aef

2018-12-12 09:05:31 +01:00

6.7 KiB

Raw Blame History

title

linktitle

description

date

publishdate

lastmod

Partial Template Lookup Order

Partial templates---like single page templates and list page templates---have a specific lookup order. However, partials are simpler in that Hugo will only check in two places:

layouts/partials/*<PARTIALNAME>.html
themes/<THEME>/layouts/partials/*<PARTIALNAME>.html

This allows a theme's end user to copy a partial's contents into a file of the same name for further customization.

Use Partials in your Templates

All partials for your Hugo project are located in a single layouts/partials directory. For better organization, you can create multiple subdirectories within partials as well:

.
└── layouts
    └── partials
        ├── footer
        │   ├── scripts.html
        │   └── site-footer.html
        ├── head
        │   ├── favicons.html
        │   ├── metadata.html
        │   ├── prerender.html
        │   └── twitter.html
        └── header
            ├── site-header.html
            └── site-nav.html

All partials are called within your templates using the following pattern:

{{ partial "<PATH>/<PARTIAL>.html" . }}

{{% note %}} One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (.) is required as the second argument to give the partial context. You can read more about "the dot" in the Hugo templating introduction. {{% /note %}}

{{% note %}} <PARTIAL> including baseof is reserved. (#5373) {{% /note %}}

As shown in the above example directory structure, you can nest your directories within partials for better source organization. You only need to call the nested partial's path relative to the partials directory:

{{ partial "header/site-header.html" . }}
{{ partial "footer/scripts.html" . }}

Variable Scoping

The second argument in a partial call is the variable being passed down. The above examples are passing the ., which tells the template receiving the partial to apply the current context.

This means the partial will only be able to access those variables. The partial 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 re-rendered on 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, you can tell Hugo to only render the partial footer.html 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.

Example `header.html`

The following header.html partial template is used for spf13.com:

{{< code file="layouts/partials/header.html" download="header.html" >}}

{{ 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> {{< /code >}}

{{% note %}} The header.html example partial was built before the introduction of block templates to Hugo. Read more on base templates and blocks for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility. {{% /note %}}

Example `footer.html`

The following footer.html partial template is used for spf13.com:

{{< code file="layouts/partials/footer.html" download="footer.html" >}}

</html> {{< /code >}}

6.7 KiB Raw Blame History