github.com/lyeb/hugo@v0.47.1/docs/content/en/templates/partials.md (about)

     1  ---
     2  title: Partial Templates
     3  linktitle: Partial Templates
     4  description: Partials are smaller, context-aware components in your list and page templates that can be used economically to keep your templating DRY.
     5  date: 2017-02-01
     6  publishdate: 2017-02-01
     7  lastmod: 2017-02-01
     8  categories: [templates]
     9  keywords: [lists,sections,partials]
    10  menu:
    11    docs:
    12      parent: "templates"
    13      weight: 90
    14  weight: 90
    15  sections_weight: 90
    16  draft: false
    17  aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/]
    18  toc: true
    19  ---
    20  
    21  {{< youtube pjS4pOLyB7c >}}
    22  
    23  ## Partial Template Lookup Order
    24  
    25  Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order][]. However, partials are simpler in that Hugo will only check in two places:
    26  
    27  1. `layouts/partials/*<PARTIALNAME>.html`
    28  2. `themes/<THEME>/layouts/partials/*<PARTIALNAME>.html`
    29  
    30  This allows a theme's end user to copy a partial's contents into a file of the same name for [further customization][customize].
    31  
    32  ## Use Partials in your Templates
    33  
    34  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:
    35  
    36  ```
    37  .
    38  └── layouts
    39      └── partials
    40          ├── footer
    41          │   ├── scripts.html
    42          │   └── site-footer.html
    43          ├── head
    44          │   ├── favicons.html
    45          │   ├── metadata.html
    46          │   ├── prerender.html
    47          │   └── twitter.html
    48          └── header
    49              ├── site-header.html
    50              └── site-nav.html
    51  ```
    52  
    53  All partials are called within your templates using the following pattern:
    54  
    55  ```
    56  {{ partial "<PATH>/<PARTIAL>.html" . }}
    57  ```
    58  
    59  {{% note %}}
    60  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](/templates/introduction/).
    61  {{% /note %}}
    62  
    63  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:
    64  
    65  ```
    66  {{ partial "header/site-header.html" . }}
    67  {{ partial "footer/scripts.html" . }}
    68  ```
    69  
    70  ### Variable Scoping
    71  
    72  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][context].
    73  
    74  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`.
    75  
    76  ### Cached Partials
    77  
    78  The [`partialCached` template function][partialcached] 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:
    79  
    80  ```
    81  {{ partialCached "footer.html" . }}
    82  ```
    83  
    84  You can also pass additional parameters to `partialCached` to create *variants* of the cached partial.
    85  
    86  For example, you can tell Hugo to only render the partial `footer.html` once per section:
    87  
    88  ```
    89  {{ partialCached "footer.html" . .Section }}
    90  ```
    91  
    92  If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need:
    93  
    94  ```
    95  {{ partialCached "footer.html" . .Params.country .Params.province }}
    96  ```
    97  
    98  Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key.
    99  
   100  ### Example `header.html`
   101  
   102  The following `header.html` partial template is used for [spf13.com](http://spf13.com/):
   103  
   104  {{< code file="layouts/partials/header.html" download="header.html" >}}
   105  <!DOCTYPE html>
   106  <html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
   107  <head>
   108      <meta charset="utf-8">
   109  
   110      {{ partial "meta.html" . }}
   111  
   112      <base href="{{ .Site.BaseURL }}">
   113      <title> {{ .Title }} : spf13.com </title>
   114      <link rel="canonical" href="{{ .Permalink }}">
   115      {{ if .RSSLink }}<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
   116  
   117      {{ partial "head_includes.html" . }}
   118  </head>
   119  <body lang="en">
   120  {{< /code >}}
   121  
   122  {{% note %}}
   123  The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) 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.
   124  {{% /note %}}
   125  
   126  ### Example `footer.html`
   127  
   128  The following `footer.html` partial template is used for [spf13.com](http://spf13.com/):
   129  
   130  {{< code file="layouts/partials/footer.html" download="footer.html" >}}
   131  <footer>
   132    <div>
   133      <p>
   134      &copy; 2013-14 Steve Francia.
   135      <a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>;
   136      please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>.
   137      </p>
   138    </div>
   139  </footer>
   140  <script type="text/javascript">
   141  
   142    var _gaq = _gaq || [];
   143    _gaq.push(['_setAccount', 'UA-XYSYXYSY-X']);
   144    _gaq.push(['_trackPageview']);
   145  
   146    (function() {
   147      var ga = document.createElement('script');
   148      ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
   149          'http://www') + '.google-analytics.com/ga.js';
   150      ga.setAttribute('async', 'true');
   151      document.documentElement.firstChild.appendChild(ga);
   152    })();
   153  
   154  </script>
   155  </body>
   156  </html>
   157  {{< /code >}}
   158  
   159  [context]: /templates/introduction/ "The most easily overlooked concept to understand about Go templating is how the dot always refers to the current context."
   160  [customize]: /themes/customizing/ "Hugo provides easy means to customize themes as long as users are familiar with Hugo's template lookup order."
   161  [listtemps]: /templates/lists/ "To effectively leverage Hugo's system, see how Hugo handles list pages, where content for sections, taxonomies, and the homepage are listed and ordered."
   162  [lookup order]: /templates/lookup-order/ "To keep your templating dry, read the documentation on Hugo's lookup order."
   163  [partialcached]: /functions/partialcached/ "Use the partial cached function to improve build times in cases where Hugo can cache partials that don't need to be rendered with every page."
   164  [singletemps]: /templates/single-page-templates/ "The most common form of template in Hugo is the single content template. Read the docs on how to create templates for individual pages."
   165  [themes]: /themes/