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

     1  ---
     2  title: Section Page Templates
     3  linktitle: Section Templates
     4  description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages.
     5  date: 2017-02-01
     6  publishdate: 2017-02-01
     7  lastmod: 2017-02-01
     8  categories: [templates]
     9  keywords: [lists,sections,templates]
    10  menu:
    11    docs:
    12      parent: "templates"
    13      weight: 40
    14  weight: 40
    15  sections_weight: 40
    16  draft: false
    17  aliases: [/templates/sections/]
    18  toc: true
    19  ---
    20  
    21  ## Add Content and Front Matter to Section Templates
    22  
    23  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.
    24  
    25  ## Section Template Lookup Order
    26  
    27  See [Template Lookup](/templates/lookup-order/).
    28  
    29  ## Page Kinds
    30  
    31  Every `Page` in Hugo has a `.Kind` attribute.
    32  
    33  | Kind           | Description                                                        | Example                                                                       |
    34  |----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------|
    35  | `home`         | The home page                                                      | `/index.html`                                                                 |
    36  | `page`         | A page showing a _regular page_                                    | `my-post` page (`/posts/my-post/index.html`)                                  |
    37  | `section`      | A page listing _regular pages_ from a given [_section_][sections]  | `posts` section (`/posts/index.html`)                                         |
    38  | `taxonomy`     | A page listing _regular pages_ from a given _taxonomy term_        | page for the term `awesome` from `tags` taxonomy (`/tags/awesome/index.html`) |
    39  | `taxonomyTerm` | A page listing terms from a given _taxonomy_                       | page for the `tags` taxonomy (`/tags/index.html`)                             |
    40  
    41  ## `.Site.GetPage` with Sections
    42  
    43  `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.
    44  
    45  The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`.
    46  
    47  You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values
    48  of `Kind` from above) and `kind value`.
    49  
    50  Examples:
    51  
    52  - `{{ .Site.GetPage "section" "posts" }}`
    53  - `{{ .Site.GetPage "page" "search" }}`
    54  
    55  ## Example: Creating a Default Section Template
    56  
    57  {{< code file="layouts/_default/section.html" download="section.html" >}}
    58  {{ define "main" }}
    59    <main>
    60        {{ .Content }}
    61            <ul class="contents">
    62            {{ range .Paginator.Pages }}
    63                <li>{{.Title}}
    64                    <div>
    65                      {{ partial "summary.html" . }}
    66                    </div>
    67                </li>
    68            {{ end }}
    69            </ul>
    70        {{ partial "pagination.html" . }}
    71    </main>
    72  {{ end }}
    73  {{< /code >}}
    74  
    75  ### Example: Using `.Site.GetPage`
    76  
    77  The `.Site.GetPage` example that follows assumes the following project directory structure:
    78  
    79  ```
    80  .
    81  └── content
    82      ├── blog
    83      │   ├── _index.md # "title: My Hugo Blog" in the front matter
    84      │   ├── post-1.md
    85      │   ├── post-2.md
    86      │   └── post-3.md
    87      └── events #Note there is no _index.md file in "events"
    88          ├── event-1.md
    89          └── event-2.md
    90  ```
    91  
    92  `.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:
    93  
    94  ```
    95  <h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1>
    96  ```
    97  
    98  Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result:
    99  
   100  ```
   101  <h1>My Hugo Blog</h1>
   102  ```
   103  
   104  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:
   105  
   106  ```
   107  <h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1>
   108  ```
   109  
   110  Which then returns the following:
   111  
   112  ```
   113  <h1>Events</h1>
   114  ```
   115  
   116  
   117  [contentorg]: /content-management/organization/
   118  [getpage]: /functions/getpage/
   119  [lists]: /templates/lists/
   120  [lookup]: /templates/lookup-order/
   121  [where]: /functions/where/
   122  [sections]: /content-management/sections/