A template is a file in the layouts directory of a project, theme, or module. Templates use [variables] , [functions], and [methods] to transform your content, resources, and data into a published page.
Hugo uses Go’s [text/template] and [html/template] packages.
The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
By default, Hugo uses the html/template package when rendering HTML files.
...
Structure # Create templates in the layouts directory in the root of your project.
Although your site may not require each of these templates, the example below is typical for a site of medium complexity.
layouts/ ├── _default/ │ ├── _markup/ │ │ ├── render-image.html <-- render hook │ │ └── render-link.html <-- render hook │ ├── baseof.html │ ├── home.html │ ├── section.html │ ├── single.html │ ├── taxonomy.
...
Lookup rules # Hugo takes the parameters listed below into consideration when choosing a template for a given page. The templates are ordered by specificity. This should feel natural, but look at the table below for concrete examples of the different parameter variations.
Kind The page Kind (the home page is one). See the example tables below per kind. This also determines if it is a single page (i.e. a regular content page.
...
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.
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 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.
...
Introduction # A home page template is used to render your site’s home page, and is the only template required for a single-page website. For example, the home page template below inherits the site’s shell from the base template and renders the home page content, such as a list of other pages.
layouts/_default/home.html {{ define "main" }} {{ .Content }} {{ range site.RegularPages }} <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} {{ end }} Lookup order # Hugo’s [template lookup order] determines the template path, allowing you to create unique templates for any page.
...
The single template below inherits the site’s shell from the [base template].
layouts/_default/single.html {{ define "main" }} <h1>{{ .Title }}</h1> {{ .Content }} {{ end }} Review the [template lookup order] to select a template path that provides the desired level of specificity.
The single template below inherits the site’s shell from the base template, and renders the page title, creation date, content, and a list of associated terms in the “tags” taxonomy.
...
Add content and front matter to section templates # To effectively leverage section templates, you should first understand Hugo’s content organization and, specifically, the purpose of _index.md for adding content and front matter to section and other list pages.
Section template lookup order # See Template Lookup.
Example: creating a default section template # layouts/_default/section.html {{ define "main" }} <main> {{ .Content }} {{ $pages := where site.RegularPages "Type" "posts" }} {{ $paginator := .
...
The [taxonomy] template below inherits the site’s shell from the [base template], and renders a list of [terms] in the current taxonomy.
layouts/_default/taxonomy.html {{ define "main" }} <h1>{{ .Title }}</h1> {{ .Content }} {{ range .Pages }} <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} {{ end }} Review the [template lookup order] to select a template path that provides the desired level of specificity.
In the example above, the taxonomy and term will be capitalized if their respective pages are not backed by files.
...
The [term] template below inherits the site’s shell from the [base template], and renders a list of pages associated with the current term.
layouts/_default/term.html {{ define "main" }} <h1>{{ .Title }}</h1> {{ .Content }} {{ range .Pages }} <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} {{ end }} Review the [template lookup order] to select a template path that provides the desired level of specificity.
In the example above, the term will be capitalized if its respective page is not backed by a file.
...
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 └── header/ ├── site-header.html └── site-nav.html All partials are called within your templates using the following pattern:
...