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

     1  ---
     2  title: Content View Templates
     3  # linktitle: Content Views
     4  description: Hugo can render alternative views of your content, which is especially useful in list and summary views.
     5  date: 2017-02-01
     6  publishdate: 2017-02-01
     7  lastmod: 2017-02-01
     8  categories: [templates]
     9  keywords: [views]
    10  menu:
    11    docs:
    12      parent: "templates"
    13      weight: 70
    14  weight: 70
    15  sections_weight: 70
    16  draft: false
    17  aliases: []
    18  toc: true
    19  ---
    20  
    21  These alternative **content views** are especially useful in [list templates][lists].
    22  
    23  The following are common use cases for content views:
    24  
    25  * You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
    26  * You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
    27  
    28  ## Create a Content View
    29  
    30  To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
    31  
    32  ```
    33    ▾ layouts/
    34      ▾ post/
    35          li.html
    36          single.html
    37          summary.html
    38      ▾ project/
    39          li.html
    40          single.html
    41          summary.html
    42  ```
    43  
    44  Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
    45  
    46  
    47  ```
    48  ▾ layouts/
    49    ▾ _default/
    50        li.html
    51        single.html
    52        summary.html
    53  ```
    54  
    55  ## Which Template Will be Rendered?
    56  
    57  The following is the [lookup order][lookup] for content views:
    58  
    59  1. `/layouts/<TYPE>/<VIEW>.html`
    60  2. `/layouts/_default/<VIEW>.html`
    61  3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
    62  4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
    63  
    64  ## Example: Content View Inside a List
    65  
    66  The following example demonstrates how to use content views inside of your [list templates][lists].
    67  
    68  ### `list.html`
    69  
    70  In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
    71  
    72  {{< code file="layouts/_default/list.html" download="list.html" >}}
    73  <main id="main">
    74    <div>
    75    <h1 id="title">{{ .Title }}</h1>
    76    {{ range .Pages }}
    77      {{ .Render "summary"}}
    78    {{ end }}
    79    </div>
    80  </main>
    81  {{< /code >}}
    82  
    83  ### `summary.html`
    84  
    85  Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
    86  
    87  {{< code file="layouts/_default/summary.html" download="summary.html" >}}
    88  <article class="post">
    89    <header>
    90      <h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
    91      <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
    92    </header>
    93    {{ .Summary }}
    94    <footer>
    95    <a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
    96    </footer>
    97  </article>
    98  {{< /code >}}
    99  
   100  ### `li.html`
   101  
   102  Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
   103  
   104  {{< code file="layouts/_default/li.html" download="li.html" >}}
   105  <li>
   106    <a href="{{ .Permalink }}">{{ .Title }}</a>
   107    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
   108  </li>
   109  {{< /code >}}
   110  
   111  [lists]: /templates/lists/
   112  [lookup]: /templates/lookup-order/
   113  [pagevars]: /variables/page/
   114  [render]: /functions/render/
   115  [single]: /templates/single-page-templates/
   116  [spf]: http://spf13.com
   117  [spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
   118  [spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
   119  [spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
   120  [summaries]: /content-management/summaries/
   121  [taxonomylists]: /templates/taxonomy-templates/