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

     1  ---
     2  title: Base Templates and Blocks
     3  linktitle:
     4  description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page).
     5  godocref: https://golang.org/pkg/text/template/#example_Template_block
     6  date: 2017-02-01
     7  publishdate: 2017-02-01
     8  lastmod: 2017-02-01
     9  categories: [templates,fundamentals]
    10  keywords: [blocks,base]
    11  menu:
    12    docs:
    13      parent: "templates"
    14      weight: 20
    15  weight: 20
    16  sections_weight: 20
    17  draft: false
    18  aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
    19  toc: true
    20  ---
    21  
    22  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.
    23  
    24  {{< youtube QVOMCYitLEc >}}
    25  
    26  ## Base Template Lookup Order
    27  
    28  The [lookup order][lookup] for base templates is as follows:
    29  
    30  1. `/layouts/section/<TYPE>-baseof.html`
    31  2. `/themes/<THEME>/layouts/section/<TYPE>-baseof.html`
    32  3. `/layouts/<TYPE>/baseof.html`
    33  4. `/themes/<THEME>/layouts/<TYPE>/baseof.html`
    34  5. `/layouts/section/baseof.html`
    35  6. `/themes/<THEME>/layouts/section/baseof.html`
    36  7. `/layouts/_default/<TYPE>-baseof.html`
    37  8. `/themes/<THEME>/layouts/_default/<TYPE>-baseof.html`
    38  9. `/layouts/_default/baseof.html`
    39  10. `/themes/<THEME>/layouts/_default/baseof.html`
    40  
    41  Variables are denoted by capitalized text set within `<>`. Note that Hugo's default behavior is for `type` to inherit from `section` unless otherwise specified.
    42  
    43  ### Example Base Template Lookup Order
    44  
    45  As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
    46  
    47  Here is the lookup order for the `post` base template:
    48  
    49  1. `/layouts/section/post-baseof.html`
    50  2. `/themes/mytheme/layouts/section/post-baseof.html`
    51  3. `/layouts/post/baseof.html`
    52  4. `/themes/mytheme/layouts/post/baseof.html`
    53  5. `/layouts/section/baseof.html`
    54  6. `/themes/mytheme/layouts/section/baseof.html`
    55  7. `/layouts/_default/post-baseof.html`
    56  8. `/themes/mytheme/layouts/_default/post-baseof.html`
    57  9. `/layouts/_default/baseof.html`
    58  10. `/themes/mytheme/layouts/_default/baseof.html`
    59  
    60  ## Define the Base Template
    61  
    62  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.
    63  
    64  {{< code file="layouts/_default/baseof.html" download="baseof.html" >}}
    65  <!DOCTYPE html>
    66  <html>
    67    <head>
    68      <meta charset="utf-8">
    69      <title>{{ block "title" . }}
    70        <!-- Blocks may include default content. -->
    71        {{ .Site.Title }}
    72      {{ end }}</title>
    73    </head>
    74    <body>
    75      <!-- Code that all your templates share, like a header -->
    76      {{ block "main" . }}
    77        <!-- The part of the page that begins to differ between templates -->
    78      {{ end }}
    79      {{ block "footer" . }}
    80      <!-- More shared code, perhaps a footer but that can be overridden if need be in  -->
    81      {{ end }}
    82    </body>
    83  </html>
    84  {{< /code >}}
    85  
    86  ## Override the Base Template
    87  
    88  From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
    89  
    90  {{< code file="layouts/_default/list.html" download="list.html" >}}
    91  {{ define "main" }}
    92    <h1>Posts</h1>
    93    {{ range .Pages }}
    94      <article>
    95        <h2>{{ .Title }}</h2>
    96        {{ .Content }}
    97      </article>
    98    {{ end }}
    99  {{ end }}
   100  {{< /code >}}
   101  
   102  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.
   103  
   104  {{% warning %}}
   105  Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
   106  
   107  ```
   108  <!-- Seemingly harmless HTML comment..that will break your layout at build -->
   109  {{ define "main" }}
   110  ...your code here
   111  {{ end }}
   112  ```
   113  [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)
   114  {{% /warning %}}
   115  
   116  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 page template][singletemplate]:
   117  
   118  {{< code file="layouts/_default/single.html" download="single.html" >}}
   119  {{ define "title" }}
   120    <!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
   121    {{ .Title }} &ndash; {{ .Site.Title }}
   122  {{ end }}
   123  {{ define "main" }}
   124    <h1>{{ .Title }}</h1>
   125    {{ .Content }}
   126  {{ end }}
   127  {{< /code >}}
   128  
   129  [hugolists]: /templates/lists
   130  [lookup]: /templates/lookup-order/
   131  [rendering the section]: /templates/section-templates/
   132  [singletemplate]: /templates/single-page-templates/