mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-13 15:26:41 -04:00
Rework the layouts doc
This commit is contained in:
Bjørn Erik Pedersen
parent
84622e67c8
commit
d5e7c03e20
@ -28,12 +28,7 @@ The homepage template is the *only* required template for building a site and th
|
||||
|
||||
## Homepage Template Lookup Order
|
||||
|
||||
The [lookup order][lookup] for the homepage template is as follows:
|
||||
|
||||
1. `/layouts/index.html`
|
||||
2. `/layouts/_default/list.html`
|
||||
3. `/themes/<THEME>/layouts/index.html`
|
||||
4. `/themes/<THEME>/layouts/_default/list.html`
|
||||
See [Template Lookup](/templates/lookup-order/).
|
||||
|
||||
## Add Content and Front Matter to the Homepage
|
||||
|
||||
|
||||
@ -31,6 +31,8 @@ Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of
|
||||
* [Section list pages][sectiontemps]
|
||||
* [RSS][rss]
|
||||
|
||||
For template lookup order, see [Template Lookup](/templates/lookup-order/).
|
||||
|
||||
The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
|
||||
|
||||
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
title: Hugo's Lookup Order
|
||||
linktitle: Template Lookup Order
|
||||
description: The lookup order is a prioritized list used by Hugo as it traverses your files looking for the appropriate corresponding file to render your content.
|
||||
description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific.
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-05-25
|
||||
categories: [templates,fundamentals]
|
||||
keywords: [lookup]
|
||||
keywords: [templates]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
@ -20,172 +20,73 @@ aliases: [/templates/lookup/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
Before creating your templates, it's important to know how Hugo looks for files within your project's [directory structure][].
|
||||
## Hugo Layouts Lookup Rules
|
||||
|
||||
Hugo uses a prioritized list called the **lookup order** as it traverses your `layouts` folder in your Hugo project *looking* for the appropriate template to render your content.
|
||||
Hugo takes the parameters listed below into consideration when choosing a layout for a given page. They are listed in a priority order. This should feel natural, but look at the table below for concrete examples of the different parameter variations.
|
||||
|
||||
The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C...and so on until it reaches the `_default/` directory for your project or theme. In many ways, the lookup order is similar to the programming concept of a [switch statement without fallthrough][switch].
|
||||
|
||||
The power of the lookup order is that it enables you to craft specific layouts and keep your templating [DRY][].
|
||||
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. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML).
|
||||
|
||||
Output Format
|
||||
: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. 'rss', 'amp', 'html') and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`, but look for less specific templates.
|
||||
|
||||
Language
|
||||
: We will consider a language code in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but we will `index.amp.html` will be chosen before `index.fr.html`.
|
||||
|
||||
Layout
|
||||
: Can be set in page front matter.
|
||||
|
||||
Type
|
||||
: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). If will always have a value, so if not set, the value is "page".
|
||||
|
||||
Section
|
||||
: Is relevant for `section`, `taxonomy` and `taxonomyTerm` types.
|
||||
|
||||
{{% note %}}
|
||||
Most Hugo websites will only need the default template files at the end of the lookup order (i.e. `_default/*.html`).
|
||||
{{% /note %}}
|
||||
|
||||
## Lookup Orders
|
||||
|
||||
The respective lookup order for each of Hugo's templates has been defined throughout the Hugo docs:
|
||||
|
||||
* [Homepage Template][home]
|
||||
* [Base Templates][base]
|
||||
* [Section Page Templates][sectionlookup]
|
||||
* [Taxonomy List Templates][taxonomylookup]
|
||||
* [Taxonomy Terms Templates][termslookup]
|
||||
* [Single Page Templates][singlelookup]
|
||||
* [RSS Templates][rsslookup]
|
||||
* [Shortcode Templates][sclookup]
|
||||
|
||||
## Template Lookup Examples
|
||||
|
||||
The lookup order is best illustrated through examples. The following shows you the process Hugo uses for finding the appropriate template to render your [single page templates][], but the concept holds true for all templates in Hugo.
|
||||
|
||||
1. The project is using the theme `mytheme` (specified in the project's [configuration][config]).
|
||||
2. The layouts and content directories for the project are as follows:
|
||||
**Tip:** The examples below looks long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates:
|
||||
|
||||
```bash
|
||||
├── _default
|
||||
│ ├── baseof.html
|
||||
│ ├── list.html
|
||||
│ └── single.html
|
||||
└── index.html
|
||||
```
|
||||
.
|
||||
├── content
|
||||
│ ├── events
|
||||
│ │ ├── _index.md
|
||||
│ │ └── my-first-event.md
|
||||
│ └── posts
|
||||
│ ├── my-first-post.md
|
||||
│ └── my-second-post.md
|
||||
├── layouts
|
||||
│ ├── _default
|
||||
│ │ └── single.html
|
||||
│ ├── posts
|
||||
│ │ └── single.html
|
||||
│ └── reviews
|
||||
│ └── reviewarticle.html
|
||||
└── themes
|
||||
└── mytheme
|
||||
└── layouts
|
||||
├── _default
|
||||
│ ├── list.html
|
||||
│ └── single.html
|
||||
└── posts
|
||||
├── list.html
|
||||
└── single.html
|
||||
```
|
||||
|
||||
|
||||
Now we can look at the front matter for the three content (i.e.`.md`) files.
|
||||
|
||||
{{% note %}}
|
||||
Only three of the four markdown files in the above project are subject to the *single* page lookup order. `_index.md` is a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are used to add content and front matter to [list pages](/templates/lists/). In this example, `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order.
|
||||
{{% /note %}}
|
||||
|
||||
### Example: `my-first-post.md`
|
||||
|
||||
{{< code file="content/posts/my-first-post.md" copy="false" >}}
|
||||
---
|
||||
title: My First Post
|
||||
date: 2017-02-19
|
||||
description: This is my first post.
|
||||
---
|
||||
{{< /code >}}
|
||||
## Hugo Layouts Lookup Rules With Theme
|
||||
|
||||
In Hugo, layouts can live in either the project's or theme's layout folder, and the most specific layout will be chosen. Hugo will interleave the lookups:
|
||||
|
||||
|
||||
1. layouts/page/index.html
|
||||
2. demoTheme/layouts/page/index.html
|
||||
3. layouts/...
|
||||
|
||||
This way it is possible to override specific templates from the theme.
|
||||
|
||||
## Examples: Layout Lookup for Regular Pages
|
||||
|
||||
{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
||||
|
||||
## Examples: Layout Lookup for Home Page
|
||||
|
||||
{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
||||
|
||||
## Examples: Layout Lookup for Section Pages
|
||||
|
||||
{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
||||
|
||||
## Examples: Layout Lookup for Taxonomy List Pages
|
||||
|
||||
{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
||||
|
||||
## Examples: Layout Lookup for Taxonomy Terms Pages
|
||||
|
||||
{{< datatable-filtered "output" "layouts" "Kind == taxonomyTerm" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
||||
|
||||
When building your site, Hugo will go through the lookup order until it finds what it needs for `my-first-post.md`:
|
||||
|
||||
1. ~~`/layouts/UNSPECIFIED/UNSPECIFIED.html`~~
|
||||
2. ~~`/layouts/posts/UNSPECIFIED.html`~~
|
||||
3. ~~`/layouts/UNSPECIFIED/single.html`~~
|
||||
4. <span class="yes">`/layouts/posts/single.html`</span>
|
||||
<br><span class="break">BREAK</span>
|
||||
5. <span class="na">`/layouts/_default/single.html`</span>
|
||||
6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
|
||||
7. <span class="na">`/themes/<THEME>/layouts/posts/UNSPECIFIED.html`</span>
|
||||
8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
|
||||
9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
|
||||
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
|
||||
|
||||
Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo the specific type and layout, it makes assumptions based on sane defaults. `my-first-post.md` does not specify a content `type` in its front matter. Therefore, Hugo assumes the content `type` and `section` (i.e. `posts`, which is defined by file location) are one in the same. ([Read more on sections][sections].)
|
||||
|
||||
`my-first-post.md` also does not specify a `layout` in its front matter. Therefore, Hugo assumes that `my-first-post.md`, which is of type `page` and a *single* piece of content, should default to the next occurrence of a `single.html` template in the lookup (#4).
|
||||
|
||||
### Example: `my-second-post.md`
|
||||
|
||||
{{< code file="content/posts/my-second-post.md" copy="false" >}}
|
||||
---
|
||||
title: My Second Post
|
||||
date: 2017-02-21
|
||||
description: This is my second post.
|
||||
type: review
|
||||
layout: reviewarticle
|
||||
---
|
||||
{{< /code >}}
|
||||
|
||||
Here is the way Hugo traverses the single-page lookup order for `my-second-post.md`:
|
||||
|
||||
1. <span class="yes">`/layouts/review/reviewarticle.html`</span>
|
||||
<br><span class="break">BREAK</span>
|
||||
2. <span class="na">`/layouts/posts/reviewarticle.html`</span>
|
||||
3. <span class="na">`/layouts/review/single.html`</span>
|
||||
4. <span class="na">`/layouts/posts/single.html`</span>
|
||||
5. <span class="na">`/layouts/_default/single.html`</span>
|
||||
6. <span class="na">`/themes/<THEME>/layouts/review/reviewarticle.html`</span>
|
||||
7. <span class="na">`/themes/<THEME>/layouts/posts/reviewarticle.html`</span>
|
||||
8. <span class="na">`/themes/<THEME>/layouts/review/single.html`</span>
|
||||
9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
|
||||
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
|
||||
|
||||
The front matter in `my-second-post.md` specifies the content `type` (i.e. `review`) as well as the `layout` (i.e. `reviewarticle`). Hugo finds the layout it needs at the top level of the lookup (#1) and does not continue to search through the other templates.
|
||||
|
||||
{{% note "Type and not Types" %}}
|
||||
Notice that the directory for the template for `my-second-post.md` is `review` and not `reviews`. This is because *type is always singular when defined in front matter*.
|
||||
{{% /note%}}
|
||||
|
||||
### Example: `my-first-event.md`
|
||||
|
||||
{{< code file="content/events/my-first-event.md" copy="false" >}}
|
||||
---
|
||||
title: My First
|
||||
date: 2017-02-21
|
||||
description: This is an upcoming event..
|
||||
---
|
||||
{{< /code >}}
|
||||
|
||||
Here is the way Hugo traverses the single-page lookup order for `my-first-event.md`:
|
||||
|
||||
1. ~~`/layouts/UNSPECIFIED/UNSPECIFIED.html`~~
|
||||
2. ~~`/layouts/events/UNSPECIFIED.html`~~
|
||||
3. ~~`/layouts/UNSPECIFIED/single.html`~~
|
||||
4. ~~`/layouts/events/single.html`~~
|
||||
5. <span class="yes">`/layouts/_default/single.html`</span>
|
||||
<br><span class="break">BREAK</span>
|
||||
6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
|
||||
7. <span class="na">`/themes/<THEME>/layouts/events/UNSPECIFIED.html`</span>
|
||||
8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
|
||||
9. <span class="na">`/themes/<THEME>/layouts/events/single.html`</span>
|
||||
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
|
||||
|
||||
|
||||
{{% note %}}
|
||||
`my-first-event.md` is significant because it demonstrates the role of the lookup order in Hugo themes. Both the root project directory *and* the `mytheme` themes directory have a file at `_default/single.html`. Understanding this order allows you to [customize Hugo themes](/themes/customizing/) by creating template files with identical names in your project directory that step in front of theme template files in the lookup. This allows you to customize the look and feel of your website while maintaining compatibility with the theme's upstream.
|
||||
{{% /note %}}
|
||||
|
||||
[base]: /templates/base/#base-template-lookup-order
|
||||
[config]: /getting-started/configuration/
|
||||
[directory structure]: /getting-started/directory-structure/
|
||||
[DRY]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
|
||||
[home]: /templates/homepage/#homepage-template-lookup-order
|
||||
[rsslookup]: /templates/rss/#rss-template-lookup-order
|
||||
[sclookup]: /templates/shortcode-templates/#shortcode-template-lookup-order
|
||||
[sections]: /content-management/sections/
|
||||
[sectionlookup]: /templates/section-templates/#section-template-lookup-order
|
||||
[single page templates]: /templates/single-page-templates/
|
||||
[singlelookup]: /templates/single-page-templates/#single-page-template-lookup-order
|
||||
[switch]: https://en.wikipedia.org/wiki/Switch_statement#Fallthrough
|
||||
[taxonomylookup]: /templates/taxonomy-templates/#taxonomy-list-template-lookup-order
|
||||
[termslookup]: /templates/taxonomy-templates/#taxonomy-terms-template-lookup-order
|
||||
|
||||
@ -6,7 +6,7 @@ date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
keywords: [lists,sections]
|
||||
keywords: [lists,sections,templates]
|
||||
menu:
|
||||
docs:
|
||||
parent: "templates"
|
||||
@ -24,18 +24,7 @@ To effectively leverage section page templates, you should first understand Hugo
|
||||
|
||||
## Section Template Lookup Order
|
||||
|
||||
The [lookup order][lookup] for section templates is as follows:
|
||||
|
||||
1. `/layouts/section/<SECTION>.html`
|
||||
2. `/layouts/<SECTION>/list.html`
|
||||
3. `/layouts/_default/section.html`
|
||||
4. `/layouts/_default/list.html`
|
||||
5. `/themes/<THEME>/layouts/section/<SECTION>.html`
|
||||
6. `/themes/<THEME>/layouts/<SECTION>/list.html`
|
||||
7. `/themes/<THEME>/layouts/_default/section.html`
|
||||
8. `/themes/<THEME>/layouts/_default/list.html`
|
||||
|
||||
{{< youtube jrMClsB3VsY >}}
|
||||
See [Template Lookup](/templates/lookup-order/).
|
||||
|
||||
## `.Site.GetPage` with Sections
|
||||
|
||||
|
||||
@ -20,22 +20,7 @@ toc: true
|
||||
|
||||
## Single Page Template Lookup Order
|
||||
|
||||
You can specify a [content's `type`][content type] and `layout` in a single content file's [front matter][]. However, you cannot specify `section` because this is determined based on file location (see [content section][section]).
|
||||
|
||||
Hugo assumes your content section and content type are the same unless you tell Hugo otherwise by providing a `type` directly in the front matter of a content file. This is why #1 and #3 come before #2 and #4, respectively, in the following lookup order. Values in angle brackets (`<>`) are variable.
|
||||
|
||||
1. `/layouts/<TYPE>/<LAYOUT>.html`
|
||||
2. `/layouts/<SECTION>/<LAYOUT>.html`
|
||||
3. `/layouts/<TYPE>/single.html`
|
||||
4. `/layouts/<SECTION>/single.html`
|
||||
5. `/layouts/_default/single.html`
|
||||
6. `/themes/<THEME>/layouts/<TYPE>/<LAYOUT>.html`
|
||||
7. `/themes/<THEME>/layouts/<SECTION>/<LAYOUT>.html`
|
||||
8. `/themes/<THEME>/layouts/<TYPE>/single.html`
|
||||
9. `/themes/<THEME>/layouts/<SECTION>/single.html`
|
||||
10. `/themes/<THEME>/layouts/_default/single.html`
|
||||
|
||||
{{< youtube ZYQ5k0RQzmo >}}
|
||||
See [Template Lookup](/templates/lookup-order/).
|
||||
|
||||
## Example Single Page Templates
|
||||
|
||||
|
||||
@ -35,32 +35,13 @@ Taxonomy list page templates are lists and therefore have all the variables and
|
||||
|
||||
### Taxonomy List Template Lookup Order
|
||||
|
||||
A taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g., http://spf13.com/topics/golang/) according to the following lookup order:
|
||||
|
||||
1. `/layouts/taxonomy/<SINGULAR>.html`
|
||||
2. `/layouts/_default/taxonomy.html`
|
||||
3. `/layouts/_default/list.html`
|
||||
4. `/themes/<THEME>/layouts/taxonomy/<SINGULAR>.html`
|
||||
5. `/themes/<THEME>/layouts/_default/taxonomy.html`
|
||||
6. `/themes/<THEME>/layouts/_default/list.html`
|
||||
See [Template Lookup](/templates/lookup-order/).
|
||||
|
||||
## Taxonomy Terms Template
|
||||
|
||||
### Taxonomy Terms Templates Lookup Order
|
||||
|
||||
A taxonomy terms page will be rendered at `example.com/<PLURALTAXONOMYNAME>`/ (e.g., http://spf13.com/topics/) according to the following lookup order:
|
||||
|
||||
1. `/layouts/taxonomy/<SINGULAR>.terms.html`
|
||||
2. `/layouts/_default/terms.html`
|
||||
3. `/themes/<THEME>/layouts/taxonomy/<SINGULAR>.terms.html`
|
||||
4. `/themes/<THEME>/layouts/_default/terms.html`
|
||||
|
||||
{{% warning "The Taxonomy Terms Template has a Unique Lookup Order" %}}
|
||||
If Hugo does not find a terms template in `layout/` or `/themes/<THEME>/layouts/`, Hugo will *not* render a taxonomy terms page.
|
||||
{{% /warning %}}
|
||||
|
||||
<!-- Begin /taxonomies/methods/ -->
|
||||
Hugo makes a set of values and methods available on the various Taxonomy structures.
|
||||
See [Template Lookup](/templates/lookup-order/).
|
||||
|
||||
### Taxonomy Methods
|
||||
|
||||
|
||||
28
layouts/shortcodes/datatable-filtered.html
Normal file
28
layouts/shortcodes/datatable-filtered.html
Normal file
@ -0,0 +1,28 @@
|
||||
{{ $package := (index .Params 0) }}
|
||||
{{ $listname := (index .Params 1) }}
|
||||
{{ $filter := split (index .Params 2) " " }}
|
||||
{{ $filter1 := index $filter 0 }}
|
||||
{{ $filter2 := index $filter 1 }}
|
||||
{{ $filter3 := index $filter 2 }}
|
||||
|
||||
{{ $list := (index (index .Site.Data.docs $package) $listname) }}
|
||||
{{ $fields := after 3 .Params }}
|
||||
{{ $list := where $list $filter1 $filter2 $filter3 }}
|
||||
|
||||
<table class="table table-bordered">
|
||||
<tr>
|
||||
{{ range $fields }}
|
||||
<th>{{ . }}</th>
|
||||
{{ end }}
|
||||
</tr>
|
||||
{{ range $list }}
|
||||
<tr>
|
||||
{{ range $k, $v := . }}
|
||||
{{ $.Scratch.Set $k $v }}
|
||||
{{ end }}
|
||||
{{ range $fields }}
|
||||
<td>{{ $.Scratch.Get . }}</td>
|
||||
{{ end }}
|
||||
</tr>
|
||||
{{ end }}
|
||||
</table>
|
||||
Loading…
x
Reference in New Issue
Block a user