mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
3886fc1fef
211a3c613 Prepare the forestry.io article for release 23995d6b4 Add forestry.io to showcase 3f177c94e Fix some typos (found by codespell) dc26e0a5a Clarify the default for site config files and multiple config files c87c9c62e Review and update the Site config documentation for consistency a29edc50c Fix the default value of rssLimit site config 83f3c46b0 Minor style fix 4f860d1a2 Typo capitalization fixes 7851345c8 Add docs about comments within templates d129b4a28 Make the recommendation to use partial over template consistent 6cd260a41 Update index.md a2787e1a4 Add Let’s Encrypt showcase 7e664f69e Update configuration.md 8002120f1 Update multilingual.md 702b46a62 Add documentation for the disableLanguages setting cb3d395de Fix content type reference d33226924 Update Page Kinds documentation 8203f649d Fix misformed markdown link 19e99c957 Add Section definition git-subtree-dir: docs git-subtree-split: 211a3c6136c69f49baeae6cd35e5a8853cddf710
122 lines
4.5 KiB
Markdown
122 lines
4.5 KiB
Markdown
---
|
|
title: Section Page Templates
|
|
linktitle: Section Templates
|
|
description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages.
|
|
date: 2017-02-01
|
|
publishdate: 2017-02-01
|
|
lastmod: 2017-02-01
|
|
categories: [templates]
|
|
keywords: [lists,sections,templates]
|
|
menu:
|
|
docs:
|
|
parent: "templates"
|
|
weight: 40
|
|
weight: 40
|
|
sections_weight: 40
|
|
draft: false
|
|
aliases: [/templates/sections/]
|
|
toc: true
|
|
---
|
|
|
|
## Add Content and Front Matter to Section Templates
|
|
|
|
To effectively leverage section page templates, you should first understand Hugo's [content organization](/content-management/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](/templates/lookup-order/).
|
|
|
|
## Page Kinds
|
|
|
|
Every `Page` in Hugo has a `.Kind` attribute.
|
|
|
|
| Kind | Description | Example |
|
|
|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------|
|
|
| `home` | The home page | `/index.html` |
|
|
| `page` | A page showing a _regular page_ | `my-post` page (`/posts/my-post/index.html`) |
|
|
| `section` | A page listing _regular pages_ from a given [_section_][sections] | `posts` section (`/posts/index.html`) |
|
|
| `taxonomy` | A page listing _regular pages_ from a given _taxonomy term_ | page for the term `awesome` from `tags` taxonomy (`/tags/awesome/index.html`) |
|
|
| `taxonomyTerm` | A page listing terms from a given _taxonomy_ | page for the `tags` taxonomy (`/tags/index.html`) |
|
|
|
|
## `.Site.GetPage` with Sections
|
|
|
|
`Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path.
|
|
|
|
The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`.
|
|
|
|
You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values
|
|
of `Kind` from above) and `kind value`.
|
|
|
|
Examples:
|
|
|
|
- `{{ .Site.GetPage "section" "posts" }}`
|
|
- `{{ .Site.GetPage "page" "search" }}`
|
|
|
|
## Example: Creating a Default Section Template
|
|
|
|
{{< code file="layouts/_default/section.html" download="section.html" >}}
|
|
{{ define "main" }}
|
|
<main>
|
|
{{ .Content }}
|
|
<ul class="contents">
|
|
{{ range .Paginator.Pages }}
|
|
<li>{{.Title}}
|
|
<div>
|
|
{{ partial "summary.html" . }}
|
|
</div>
|
|
</li>
|
|
{{ end }}
|
|
</ul>
|
|
{{ partial "pagination.html" . }}
|
|
</main>
|
|
{{ end }}
|
|
{{< /code >}}
|
|
|
|
### Example: Using `.Site.GetPage`
|
|
|
|
The `.Site.GetPage` example that follows assumes the following project directory structure:
|
|
|
|
```
|
|
.
|
|
└── content
|
|
├── blog
|
|
│ ├── _index.md # "title: My Hugo Blog" in the front matter
|
|
│ ├── post-1.md
|
|
│ ├── post-2.md
|
|
│ └── post-3.md
|
|
└── events #Note there is no _index.md file in "events"
|
|
├── event-1.md
|
|
└── event-2.md
|
|
```
|
|
|
|
`.Site.GetPage` will return `nil` if no `_index.md` page is found. Therefore, if `content/blog/_index.md` does not exist, the template will output the section name:
|
|
|
|
```
|
|
<h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1>
|
|
```
|
|
|
|
Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result:
|
|
|
|
```
|
|
<h1>My Hugo Blog</h1>
|
|
```
|
|
|
|
If we try the same code with the `events` section, however, Hugo will default to the section title because there is no `content/events/_index.md` from which to pull content and front matter:
|
|
|
|
```
|
|
<h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1>
|
|
```
|
|
|
|
Which then returns the following:
|
|
|
|
```
|
|
<h1>Events</h1>
|
|
```
|
|
|
|
|
|
[contentorg]: /content-management/organization/
|
|
[getpage]: /functions/getpage/
|
|
[lists]: /templates/lists/
|
|
[lookup]: /templates/lookup-order/
|
|
[where]: /functions/where/
|
|
[sections]: /content-management/sections/
|