diff --git a/config.toml b/config.toml index 0c7e18a6a..1b723c7cd 100644 --- a/config.toml +++ b/config.toml @@ -26,7 +26,7 @@ layoutDir = "layouts" # Enable Logging log = true # Log Filepath (if set, logging enabled automatically) -logFil = "" +logFile = "" # This accepts yaml, toml, or json metaDataFormat = "yaml" # This intelligently adds an "s" to the titles of list pages diff --git a/content/templates/go-templates.md b/content/templates/go-templates.md index d3650fba9..26d2d8a89 100644 --- a/content/templates/go-templates.md +++ b/content/templates/go-templates.md @@ -1,7 +1,7 @@ --- title: Go Template Primer linktitle: Go Template Primer -description: Hugo uses Go html/template library, an extremely lightweight and performant, engine as the basis for all Hugo templating. +description: Hugo uses Go's html/template library, an extremely lightweight and performant engine, as the basis for all Hugo templating. godocref: https://golang.org/pkg/html/template/ date: 2017-02-01 publishdate: 2017-02-01 diff --git a/content/templates/homepage.md b/content/templates/homepage.md index dc58b6dbc..654457e71 100644 --- a/content/templates/homepage.md +++ b/content/templates/homepage.md @@ -42,9 +42,7 @@ Note that a homepage can also have a content file with front matter. This conten ## Example Homepage Template -The following is an example of a homepage template. - -It makes use of [partial templates][partials] and uses a similar approach as a [Hugo list template][lists]. +The following is an example of a homepage template makes use of [partial][partials] and [block][] templates. {{% code file="layouts/index.html" download="index.html" %}} ```html @@ -63,6 +61,7 @@ It makes use of [partial templates][partials] and uses a similar approach as a [ ``` {{% /code %}} +[block]: /templates/base/ [contentorg]: /content-management/organization/ [lists]: /templates/lists/ [lookup]: /templates/lookup-order/ diff --git a/content/templates/lists.md b/content/templates/lists.md index d38ed4cfa..56df1dd4f 100644 --- a/content/templates/lists.md +++ b/content/templates/lists.md @@ -1,7 +1,7 @@ --- title: Introduction to Lists in Hugo linktitle: Hugo Lists -description: Lists have a specific meaning and usage in Hugo. If you want to know how to render your site homepage, section homepage, taxonomy list, or taxonomy terms list, start here. +description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list. date: 2017-02-01 publishdate: 2017-02-01 lastmod: 2017-02-01 diff --git a/content/templates/partials.md b/content/templates/partials.md index b948203a0..e74de4542 100644 --- a/content/templates/partials.md +++ b/content/templates/partials.md @@ -14,36 +14,94 @@ toc: true wip: true --- -## Partials vs Templates +In practice, splitting out reusable template portions into **partial templates** to be included anywhere help keep your templating DRY. -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 partial subdirectories like `/layouts/partials/post/tag/`. +## Partial Template Lookup Order -Partials are especially important for [themes][] because they give theme users an opportunity to [overwrite just a small portion of a theme][customize] while maintaining compatibility with the theme's upstream. +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: -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. +1. `layouts/partials/*.html` +2. `themes//layouts/partials/*.html` -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. +This allows a theme's end user to copy a partial's contents into a file of the same name for [further customization][customize]. -```bash -▾ layouts/ - ▾ partials/ - header.html - footer.html +## Using 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 ``` -## Partial vs Template +All partials are called within your templates using the following pattern: -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. +``` +{{ partial "/.html" . }} +``` -With the addition of the theme system in v0.11, it became apparent that a theme & override-aware partial was needed. +{{% 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 [Go Template Primer](/templates/go-templates/). +{{% /note %}} -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. +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: -## Example `header.html` +```golang +{{ partial "header/site-header.html" . }} +{{ partial "footer/scripts.html" . }} +``` -This header template is used for [spf13.com](http://spf13.com/): +{{% note %}} +Before v0.12, Hugo used the `template` call to include partial templates. When using Hugo v0.12 and newer, be sure to use the `{{ partial "/.html" . }}` syntax. The old approach will still work but has fewer benefits. +{{% /note %}} -{{% code file="layouts/partials/header.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][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][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: + +``` +{{ 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](http://spf13.com/): + +{{% code file="layouts/partials/header.html" download="header.html" %}} ```html @@ -63,11 +121,15 @@ This header template is used for [spf13.com](http://spf13.com/): ``` {{% /code %}} -## Example `footer.html` +{{% note %}} +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. +{{% /note %}} -This footer template is used for [spf13.com](http://spf13.com/): +### Example `footer.html` -{{% code file="layouts/partials/footer.html" %}} +The following `footer.html` partial template is used for [spf13.com](http://spf13.com/): + +{{% code file="layouts/partials/footer.html" download="footer.html" %}} ```html