hugo/docs/content/en/templates/base.md

95 lines
3.1 KiB
Markdown
Raw Normal View History

---
Squashed 'docs/' changes from 9b06f951e..fcc3ed651 fcc3ed651 Remove some expired new-in a9c5981f5 Fix cascade example 82bb250fa Add some lines about permalinks tokens in front matter 328fe564e Remove some outdated new-in fb140b153 Hide showcase menu entry 42d9d1c79 Update image formats from which EXIF data can be extracted 09ad56b6e netlify: Hugo 0.130.0 1d503f846 Merge branch 'tempv0.130.0' e2458074d math: Add trigonometric functions and some angle helper functions 392afc8f9 Disable the showcase section for now 0300750f2 Improve example of image render hook 60a9306af Improve description of the .Site.RegularPages method 8d759175d Fix typos 55daa4554 Update XxHash.md 397c81cb7 Add namespace for hash functions 70fe8d2f0 netlify: Bump Hugo 0.129.0 5a9771aff Merge branch 'tempv0.129.0' f9146575b Fix typo e6e1fea49 Fix typo in Hugo docs | functions | partial 732d10ec4 source: Expose GitInfo Body 34c97e639 netlify: Hugo 0.128.2 3270587e9 Fix typo 727c5396e netlify: Hugo 0.128.1 80b6ae99c Update GitHub Pages workflow file example 027134102 Update GitHub Pages workflow file example 2600a8a2e Miscellaneous edits 3fdd5819b Update Build.md 7764005c3 Improve example of render hook directory structure 5e3941d82 Fix typos 748bf065f Restructure templates section fafbf6566 Update Defer.md 012162e0d Document changes to template functions in v0.128.0 0990ce35b quick-reference: Update emojis 6677a30ef Update Goldmark configuration documentation 4449d530d Document new pagination config 0af8be439 Update Defer.md 56348196d netlify: Hugo 0.128.0 d67b6d82e Update content/en/functions/templates/Defer.md 23d996b3d Update content/en/functions/templates/Defer.md 7f7fb2f27 Document templates.Defer 5ada1e9d5 Fix docs merge (remove shortcode) d27ee6156 Merge branch 'tempv0.128.0' 5d7317c84 Fix typo 7c18ee546 Update theme 83bfea63b Update theme b274b3238 Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' ff34a035a deploy: Add stripIndexHtml target option d9e964bdb markup/goldmark: Add the Hugo Goldmark Extras "delete" extension ac5bd16d2 deps: Upgrade github.com/alecthomas/chroma v2.13.0 => v2.14.0 25377171b config: Remove extraneous BuildConfig setting 0d2044f6d docs: Regen docshelper a2548dac9 markup/goldmark: Support extras extension 9d0c86ee8 commands: Add gen chromastyles --lineNumbersTableStyle flag git-subtree-dir: docs git-subtree-split: fcc3ed651a1b6431303c2f88f20fa38531c52b3d
2024-08-09 09:17:43 -04:00
title: Base templates
description: The base and block construct allows you to define the outer shell of your master templates (i.e., the chrome of the page).
categories: [templates,fundamentals]
Squashed 'docs/' changes from 9b06f951e..fcc3ed651 fcc3ed651 Remove some expired new-in a9c5981f5 Fix cascade example 82bb250fa Add some lines about permalinks tokens in front matter 328fe564e Remove some outdated new-in fb140b153 Hide showcase menu entry 42d9d1c79 Update image formats from which EXIF data can be extracted 09ad56b6e netlify: Hugo 0.130.0 1d503f846 Merge branch 'tempv0.130.0' e2458074d math: Add trigonometric functions and some angle helper functions 392afc8f9 Disable the showcase section for now 0300750f2 Improve example of image render hook 60a9306af Improve description of the .Site.RegularPages method 8d759175d Fix typos 55daa4554 Update XxHash.md 397c81cb7 Add namespace for hash functions 70fe8d2f0 netlify: Bump Hugo 0.129.0 5a9771aff Merge branch 'tempv0.129.0' f9146575b Fix typo e6e1fea49 Fix typo in Hugo docs | functions | partial 732d10ec4 source: Expose GitInfo Body 34c97e639 netlify: Hugo 0.128.2 3270587e9 Fix typo 727c5396e netlify: Hugo 0.128.1 80b6ae99c Update GitHub Pages workflow file example 027134102 Update GitHub Pages workflow file example 2600a8a2e Miscellaneous edits 3fdd5819b Update Build.md 7764005c3 Improve example of render hook directory structure 5e3941d82 Fix typos 748bf065f Restructure templates section fafbf6566 Update Defer.md 012162e0d Document changes to template functions in v0.128.0 0990ce35b quick-reference: Update emojis 6677a30ef Update Goldmark configuration documentation 4449d530d Document new pagination config 0af8be439 Update Defer.md 56348196d netlify: Hugo 0.128.0 d67b6d82e Update content/en/functions/templates/Defer.md 23d996b3d Update content/en/functions/templates/Defer.md 7f7fb2f27 Document templates.Defer 5ada1e9d5 Fix docs merge (remove shortcode) d27ee6156 Merge branch 'tempv0.128.0' 5d7317c84 Fix typo 7c18ee546 Update theme 83bfea63b Update theme b274b3238 Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' ff34a035a deploy: Add stripIndexHtml target option d9e964bdb markup/goldmark: Add the Hugo Goldmark Extras "delete" extension ac5bd16d2 deps: Upgrade github.com/alecthomas/chroma v2.13.0 => v2.14.0 25377171b config: Remove extraneous BuildConfig setting 0d2044f6d docs: Regen docshelper a2548dac9 markup/goldmark: Support extras extension 9d0c86ee8 commands: Add gen chromastyles --lineNumbersTableStyle flag git-subtree-dir: docs git-subtree-split: fcc3ed651a1b6431303c2f88f20fa38531c52b3d
2024-08-09 09:17:43 -04:00
keywords: []
menu:
docs:
parent: templates
Squashed 'docs/' changes from 9b06f951e..fcc3ed651 fcc3ed651 Remove some expired new-in a9c5981f5 Fix cascade example 82bb250fa Add some lines about permalinks tokens in front matter 328fe564e Remove some outdated new-in fb140b153 Hide showcase menu entry 42d9d1c79 Update image formats from which EXIF data can be extracted 09ad56b6e netlify: Hugo 0.130.0 1d503f846 Merge branch 'tempv0.130.0' e2458074d math: Add trigonometric functions and some angle helper functions 392afc8f9 Disable the showcase section for now 0300750f2 Improve example of image render hook 60a9306af Improve description of the .Site.RegularPages method 8d759175d Fix typos 55daa4554 Update XxHash.md 397c81cb7 Add namespace for hash functions 70fe8d2f0 netlify: Bump Hugo 0.129.0 5a9771aff Merge branch 'tempv0.129.0' f9146575b Fix typo e6e1fea49 Fix typo in Hugo docs | functions | partial 732d10ec4 source: Expose GitInfo Body 34c97e639 netlify: Hugo 0.128.2 3270587e9 Fix typo 727c5396e netlify: Hugo 0.128.1 80b6ae99c Update GitHub Pages workflow file example 027134102 Update GitHub Pages workflow file example 2600a8a2e Miscellaneous edits 3fdd5819b Update Build.md 7764005c3 Improve example of render hook directory structure 5e3941d82 Fix typos 748bf065f Restructure templates section fafbf6566 Update Defer.md 012162e0d Document changes to template functions in v0.128.0 0990ce35b quick-reference: Update emojis 6677a30ef Update Goldmark configuration documentation 4449d530d Document new pagination config 0af8be439 Update Defer.md 56348196d netlify: Hugo 0.128.0 d67b6d82e Update content/en/functions/templates/Defer.md 23d996b3d Update content/en/functions/templates/Defer.md 7f7fb2f27 Document templates.Defer 5ada1e9d5 Fix docs merge (remove shortcode) d27ee6156 Merge branch 'tempv0.128.0' 5d7317c84 Fix typo 7c18ee546 Update theme 83bfea63b Update theme b274b3238 Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' ff34a035a deploy: Add stripIndexHtml target option d9e964bdb markup/goldmark: Add the Hugo Goldmark Extras "delete" extension ac5bd16d2 deps: Upgrade github.com/alecthomas/chroma v2.13.0 => v2.14.0 25377171b config: Remove extraneous BuildConfig setting 0d2044f6d docs: Regen docshelper a2548dac9 markup/goldmark: Support extras extension 9d0c86ee8 commands: Add gen chromastyles --lineNumbersTableStyle flag git-subtree-dir: docs git-subtree-split: fcc3ed651a1b6431303c2f88f20fa38531c52b3d
2024-08-09 09:17:43 -04:00
weight: 50
weight: 50
toc: true
aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
---
The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary.
{{< youtube QVOMCYitLEc >}}
## Base template lookup order
The base template lookup order closely follows that of the template it applies to (e.g. `_default/list.html`).
See [Template Lookup Order](/templates/lookup-order/) for details and examples.
## Define the base template
The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
{{< code file=layouts/_default/baseof.html >}}
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>{{ block "title" . }}
<!-- Blocks may include default content. -->
{{ .Site.Title }}
{{ end }}</title>
</head>
<body>
<!-- Code that all your templates share, like a header -->
{{ block "main" . }}
<!-- The part of the page that begins to differ between templates -->
{{ end }}
{{ block "footer" . }}
<!-- More shared code, perhaps a footer but that can be overridden if need be in -->
{{ end }}
</body>
</html>
{{< /code >}}
## Override the base template
Squashed 'docs/' changes from 9b06f951e..fcc3ed651 fcc3ed651 Remove some expired new-in a9c5981f5 Fix cascade example 82bb250fa Add some lines about permalinks tokens in front matter 328fe564e Remove some outdated new-in fb140b153 Hide showcase menu entry 42d9d1c79 Update image formats from which EXIF data can be extracted 09ad56b6e netlify: Hugo 0.130.0 1d503f846 Merge branch 'tempv0.130.0' e2458074d math: Add trigonometric functions and some angle helper functions 392afc8f9 Disable the showcase section for now 0300750f2 Improve example of image render hook 60a9306af Improve description of the .Site.RegularPages method 8d759175d Fix typos 55daa4554 Update XxHash.md 397c81cb7 Add namespace for hash functions 70fe8d2f0 netlify: Bump Hugo 0.129.0 5a9771aff Merge branch 'tempv0.129.0' f9146575b Fix typo e6e1fea49 Fix typo in Hugo docs | functions | partial 732d10ec4 source: Expose GitInfo Body 34c97e639 netlify: Hugo 0.128.2 3270587e9 Fix typo 727c5396e netlify: Hugo 0.128.1 80b6ae99c Update GitHub Pages workflow file example 027134102 Update GitHub Pages workflow file example 2600a8a2e Miscellaneous edits 3fdd5819b Update Build.md 7764005c3 Improve example of render hook directory structure 5e3941d82 Fix typos 748bf065f Restructure templates section fafbf6566 Update Defer.md 012162e0d Document changes to template functions in v0.128.0 0990ce35b quick-reference: Update emojis 6677a30ef Update Goldmark configuration documentation 4449d530d Document new pagination config 0af8be439 Update Defer.md 56348196d netlify: Hugo 0.128.0 d67b6d82e Update content/en/functions/templates/Defer.md 23d996b3d Update content/en/functions/templates/Defer.md 7f7fb2f27 Document templates.Defer 5ada1e9d5 Fix docs merge (remove shortcode) d27ee6156 Merge branch 'tempv0.128.0' 5d7317c84 Fix typo 7c18ee546 Update theme 83bfea63b Update theme b274b3238 Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' ff34a035a deploy: Add stripIndexHtml target option d9e964bdb markup/goldmark: Add the Hugo Goldmark Extras "delete" extension ac5bd16d2 deps: Upgrade github.com/alecthomas/chroma v2.13.0 => v2.14.0 25377171b config: Remove extraneous BuildConfig setting 0d2044f6d docs: Regen docshelper a2548dac9 markup/goldmark: Support extras extension 9d0c86ee8 commands: Add gen chromastyles --lineNumbersTableStyle flag git-subtree-dir: docs git-subtree-split: fcc3ed651a1b6431303c2f88f20fa38531c52b3d
2024-08-09 09:17:43 -04:00
The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
{{< code file=layouts/_default/list.html >}}
{{ define "main" }}
<h1>Posts</h1>
{{ range .Pages }}
<article>
<h2>{{ .Title }}</h2>
{{ .Content }}
</article>
{{ end }}
{{ end }}
{{< /code >}}
This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
{{% note %}}
Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
```go-html-template
<!-- Seemingly harmless HTML comment..that will break your layout at build -->
{{ define "main" }}
...your code here
{{ end }}
```
[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6)
{{% /note %}}
Squashed 'docs/' changes from 9b06f951e..fcc3ed651 fcc3ed651 Remove some expired new-in a9c5981f5 Fix cascade example 82bb250fa Add some lines about permalinks tokens in front matter 328fe564e Remove some outdated new-in fb140b153 Hide showcase menu entry 42d9d1c79 Update image formats from which EXIF data can be extracted 09ad56b6e netlify: Hugo 0.130.0 1d503f846 Merge branch 'tempv0.130.0' e2458074d math: Add trigonometric functions and some angle helper functions 392afc8f9 Disable the showcase section for now 0300750f2 Improve example of image render hook 60a9306af Improve description of the .Site.RegularPages method 8d759175d Fix typos 55daa4554 Update XxHash.md 397c81cb7 Add namespace for hash functions 70fe8d2f0 netlify: Bump Hugo 0.129.0 5a9771aff Merge branch 'tempv0.129.0' f9146575b Fix typo e6e1fea49 Fix typo in Hugo docs | functions | partial 732d10ec4 source: Expose GitInfo Body 34c97e639 netlify: Hugo 0.128.2 3270587e9 Fix typo 727c5396e netlify: Hugo 0.128.1 80b6ae99c Update GitHub Pages workflow file example 027134102 Update GitHub Pages workflow file example 2600a8a2e Miscellaneous edits 3fdd5819b Update Build.md 7764005c3 Improve example of render hook directory structure 5e3941d82 Fix typos 748bf065f Restructure templates section fafbf6566 Update Defer.md 012162e0d Document changes to template functions in v0.128.0 0990ce35b quick-reference: Update emojis 6677a30ef Update Goldmark configuration documentation 4449d530d Document new pagination config 0af8be439 Update Defer.md 56348196d netlify: Hugo 0.128.0 d67b6d82e Update content/en/functions/templates/Defer.md 23d996b3d Update content/en/functions/templates/Defer.md 7f7fb2f27 Document templates.Defer 5ada1e9d5 Fix docs merge (remove shortcode) d27ee6156 Merge branch 'tempv0.128.0' 5d7317c84 Fix typo 7c18ee546 Update theme 83bfea63b Update theme b274b3238 Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' ff34a035a deploy: Add stripIndexHtml target option d9e964bdb markup/goldmark: Add the Hugo Goldmark Extras "delete" extension ac5bd16d2 deps: Upgrade github.com/alecthomas/chroma v2.13.0 => v2.14.0 25377171b config: Remove extraneous BuildConfig setting 0d2044f6d docs: Regen docshelper a2548dac9 markup/goldmark: Support extras extension 9d0c86ee8 commands: Add gen chromastyles --lineNumbersTableStyle flag git-subtree-dir: docs git-subtree-split: fcc3ed651a1b6431303c2f88f20fa38531c52b3d
2024-08-09 09:17:43 -04:00
The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your default [single template]:
{{< code file=layouts/_default/single.html >}}
{{ define "title" }}
<!-- This will override the default value set in baseof.html; i.e., "{{ .Site.Title }}" in the original example-->
{{ .Title }} &ndash; {{ .Site.Title }}
{{ end }}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
{{< /code >}}
Squashed 'docs/' changes from 9b06f951e..fcc3ed651 fcc3ed651 Remove some expired new-in a9c5981f5 Fix cascade example 82bb250fa Add some lines about permalinks tokens in front matter 328fe564e Remove some outdated new-in fb140b153 Hide showcase menu entry 42d9d1c79 Update image formats from which EXIF data can be extracted 09ad56b6e netlify: Hugo 0.130.0 1d503f846 Merge branch 'tempv0.130.0' e2458074d math: Add trigonometric functions and some angle helper functions 392afc8f9 Disable the showcase section for now 0300750f2 Improve example of image render hook 60a9306af Improve description of the .Site.RegularPages method 8d759175d Fix typos 55daa4554 Update XxHash.md 397c81cb7 Add namespace for hash functions 70fe8d2f0 netlify: Bump Hugo 0.129.0 5a9771aff Merge branch 'tempv0.129.0' f9146575b Fix typo e6e1fea49 Fix typo in Hugo docs | functions | partial 732d10ec4 source: Expose GitInfo Body 34c97e639 netlify: Hugo 0.128.2 3270587e9 Fix typo 727c5396e netlify: Hugo 0.128.1 80b6ae99c Update GitHub Pages workflow file example 027134102 Update GitHub Pages workflow file example 2600a8a2e Miscellaneous edits 3fdd5819b Update Build.md 7764005c3 Improve example of render hook directory structure 5e3941d82 Fix typos 748bf065f Restructure templates section fafbf6566 Update Defer.md 012162e0d Document changes to template functions in v0.128.0 0990ce35b quick-reference: Update emojis 6677a30ef Update Goldmark configuration documentation 4449d530d Document new pagination config 0af8be439 Update Defer.md 56348196d netlify: Hugo 0.128.0 d67b6d82e Update content/en/functions/templates/Defer.md 23d996b3d Update content/en/functions/templates/Defer.md 7f7fb2f27 Document templates.Defer 5ada1e9d5 Fix docs merge (remove shortcode) d27ee6156 Merge branch 'tempv0.128.0' 5d7317c84 Fix typo 7c18ee546 Update theme 83bfea63b Update theme b274b3238 Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' ff34a035a deploy: Add stripIndexHtml target option d9e964bdb markup/goldmark: Add the Hugo Goldmark Extras "delete" extension ac5bd16d2 deps: Upgrade github.com/alecthomas/chroma v2.13.0 => v2.14.0 25377171b config: Remove extraneous BuildConfig setting 0d2044f6d docs: Regen docshelper a2548dac9 markup/goldmark: Support extras extension 9d0c86ee8 commands: Add gen chromastyles --lineNumbersTableStyle flag git-subtree-dir: docs git-subtree-split: fcc3ed651a1b6431303c2f88f20fa38531c52b3d
2024-08-09 09:17:43 -04:00
[single template]: /templates/types/#single