hugo/docs/content/en/templates/views.md

122 lines
4.3 KiB
Markdown
Raw Normal View History

---
title: Content View Templates
# linktitle: Content Views
description: Hugo can render alternative views of your content, which is especially useful in list and summary views.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [templates]
keywords: [views]
menu:
docs:
parent: "templates"
weight: 70
weight: 70
sections_weight: 70
draft: false
aliases: []
toc: true
---
These alternative **content views** are especially useful in [list templates][lists].
The following are common use cases for content views:
* You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
* 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.
## Create a Content View
Squashed 'docs/' changes from 785e375f..49809a03 49809a03 Merge commit '20a631b4964fc0ab9137cce1e41774cbc17de044' 20a631b4 Squashed 'themes/gohugoioTheme/' changes from b8202f539..dafc91ff1 8b58f565 Re-generate CLI docs 4653a724 Add Netlify deployment badge 2d6246bc Remove some deprecated site variables e6777153 Improve Algolia Search Display Styling 1570999f Add missing "." in front of gitlab-ci.yaml example b922ae7d This adds documentation to the new configDir/Environment logic from .53 (#729) 7cff379f Correctly escape multi-word taxonomy terms in example 2dfeeda4 fix typo by removing stray paren 0870bd9a Fix typo in `paginate` description 91e8be85 Fixes https://github.com/gohugoio/hugo/issues/5609 c1db65ec Make the dummy URL more obvious b4589ff0 Fix a link b73dcb9a Consistently use "posts" as section name in examples 7a56abbc Format definitions a9c6fd9b Minor clarification over the last commit 5c86bdc8 Add alternative instructions for Quick Start for non-git users dafe7ee9 Add Visual Studio Code plug-ins 110ed19e Update HUGO_VERSION 2abd031a Update page.md b332f7b9 Update page.md f5a8c9d4 Update static-files.md 6d0c155c Add note about relative protocol URLs a13751ac Theme Warning: Remove note about unquoted URLs 4c8f7d68 Incorporate feedback 6f2b9cf0 Update Creating Themes Warning 40d88d98 Fix ToC example to use binary true/false 4a11f3f1 Fix typo 2dbfc0a4 Fix a typo in taxonomies d63790ef Do not mark UndocumentedFeature issues as stale d7aff095 Regenerate docs.json 71c0826f Update transform.Unmarshal.md git-subtree-dir: docs git-subtree-split: 49809a038b2691637bab7f3f2e385dde654a88b8
2019-02-01 08:01:04 +00:00
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 `posts` 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.
```
▾ layouts/
Squashed 'docs/' changes from 785e375f..49809a03 49809a03 Merge commit '20a631b4964fc0ab9137cce1e41774cbc17de044' 20a631b4 Squashed 'themes/gohugoioTheme/' changes from b8202f539..dafc91ff1 8b58f565 Re-generate CLI docs 4653a724 Add Netlify deployment badge 2d6246bc Remove some deprecated site variables e6777153 Improve Algolia Search Display Styling 1570999f Add missing "." in front of gitlab-ci.yaml example b922ae7d This adds documentation to the new configDir/Environment logic from .53 (#729) 7cff379f Correctly escape multi-word taxonomy terms in example 2dfeeda4 fix typo by removing stray paren 0870bd9a Fix typo in `paginate` description 91e8be85 Fixes https://github.com/gohugoio/hugo/issues/5609 c1db65ec Make the dummy URL more obvious b4589ff0 Fix a link b73dcb9a Consistently use "posts" as section name in examples 7a56abbc Format definitions a9c6fd9b Minor clarification over the last commit 5c86bdc8 Add alternative instructions for Quick Start for non-git users dafe7ee9 Add Visual Studio Code plug-ins 110ed19e Update HUGO_VERSION 2abd031a Update page.md b332f7b9 Update page.md f5a8c9d4 Update static-files.md 6d0c155c Add note about relative protocol URLs a13751ac Theme Warning: Remove note about unquoted URLs 4c8f7d68 Incorporate feedback 6f2b9cf0 Update Creating Themes Warning 40d88d98 Fix ToC example to use binary true/false 4a11f3f1 Fix typo 2dbfc0a4 Fix a typo in taxonomies d63790ef Do not mark UndocumentedFeature issues as stale d7aff095 Regenerate docs.json 71c0826f Update transform.Unmarshal.md git-subtree-dir: docs git-subtree-split: 49809a038b2691637bab7f3f2e385dde654a88b8
2019-02-01 08:01:04 +00:00
▾ posts/
li.html
single.html
summary.html
▾ project/
li.html
single.html
summary.html
```
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.
```
▾ layouts/
▾ _default/
li.html
single.html
summary.html
```
## Which Template Will be Rendered?
The following is the [lookup order][lookup] for content views:
1. `/layouts/<TYPE>/<VIEW>.html`
2. `/layouts/_default/<VIEW>.html`
3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
## Example: Content View Inside a List
The following example demonstrates how to use content views inside of your [list templates][lists].
### `list.html`
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:
{{< code file="layouts/_default/list.html" download="list.html" >}}
<main id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
Squashed 'docs/' changes from f59b3ab06..cfe89ecbc cfe89ecbc Set all *.png files under static/images to mode 0644 d847ccd8b More spelling error fixes bf1405d92 Correction: .Pages on homepage is same as .Site.RegularPages 7efa41ff5 Merge commit 'd137efe0222269e09b427325176f0044558e3cc5' d137efe02 Squashed 'themes/gohugoioTheme/' changes from f31a3dc8..66249819 50df8bfb8 Replace .Data.Pages with .Pages 85d3712d0 Mention the newScratch template func 1c234db1b Release 0.44 a51cb3e36 Merge branch 'temp44' ec424a5e2 releaser: Prepare repository for 0.45-DEV 425e85574 releaser: Add release notes to /docs for release of 0.44 e6f9c65a2 releaser: Bump versions for release of 0.44 45548a5c9 Arch Linux: Partial upgrades are unsupported c0430f8f9 Update MenuEntry properties documentation 79109b685 Refresh the documentation on staticDir config parameter 80ed4592b Remove duplicate links; also sort them alphabetically f00a4e232 HTTPS links to third-party sites 2f6f682ba Fixed a typo 4be105202 add openbsd howto install 39808f50a Fix typo b55c0f3a0 Fix URL to hugotest 2fb157237 Release Hugo 0.43 e8af6a970 Merge branch 'temp43' 563dd4173 Adjust release notes 50aed2e52 releaser: Prepare repository for 0.44-DEV 363b363ff releaser: Add release notes to /docs for release of 0.43 93bfbef62 releaser: Bump versions for release of 0.43 893a27d33 Fix typos fe5908257 Celebrate: a few typo and grammar fixes bb20442df Merge commit '98293eaa1570b5aff4452021c8b6d6c8560b3f06' ef3d63936 Add a newScratch template func bf100a3cd Merge branch 'release-0.42.2' f1133c544 releaser: Prepare repository for 0.43-DEV 2ce058057 releaser: Add release notes to /docs for release of 0.42.2 6073927c6 releaser: Bump versions for release of 0.42.2 3bafddd52 releaser: Prepare repository for 0.43-DEV 8b9f805bd releaser: Add release notes to /docs for release of 0.42.1 efb6638ba releaser: Bump versions for release of 0.42.1 1e74ffbe0 releaser: Prepare repository for 0.43-DEV 2d2d0f8ab releaser: Add release notes to /docs for release of 0.42 17f685813 releaser: Bump versions for release of 0.42 67ef1a0e1 docs: Update theme documentation d74874e1e docs: Remove some files now moved 771d50cf3 Merge commit 'b239595af5a9fc1fc9a1ccc666c3ab06ccc32f04' f9b5fd2d2 tplimpl: Remove speakerdeck shortcode 523206579 tpl/strings: strings.RuneCount b389efc88 tpl: Add strings.Repeat a41ad0254 Add a BlackFriday option for rel="noreferrer" on external links a6e279362 Add a BlackFriday option for rel="nofollow" on external links 7e2c9846e releaser: Prepare repository for 0.42-DEV b4f81c38a releaser: Add release notes to /docs for release of 0.41 55667b3a1 releaser: Bump versions for release of 0.41 afceb02d3 docs: Document the GDPR Privacy Config 8b8289027 Merge commit 'd2b1030060d3c91d5f9ffa3456418da16bd74f1d' be04a8886 Merge branch 'release-0.40.3' 33ca0b8da releaser: Prepare repository for 0.41-DEV 8c9a5a850 releaser: Add release notes to /docs for release of 0.40.3 85845a4fd releaser: Bump versions for release of 0.40.3 9af79e531 Merge commit '83bef6955e014d40c0f00db9cebe09113154e999' c4200dd0e Fix typo 8f8323336 releaser: Prepare repository for 0.41-DEV 9fab87505 releaser: Add release notes to /docs for release of 0.40.2 83648c666 releaser: Bump versions for release of 0.40.2 e6434d104 releaser: Prepare repository for 0.41-DEV 9389b2973 releaser: Add release notes to /docs for release of 0.40.1 32979e28a releaser: Bump versions for release of 0.40.1 196174a76 releaser: Prepare repository for 0.41-DEV 490a997bb releaser: Add release notes to /docs for release of 0.40 018aa6471 releaser: Bump versions for release of 0.40 92221934c Merge commit 'a215abf70e018f4bf40d6c09d8bd148d8684b33d' 0a58ef56e Merge commit 'd2ec1a06df8ab6b17ad05cb008d5701b40327d47' 312ab58c6 Improve .Get docs e43e8cee3 .Get function: fix syntax signature bb16150bc releaser: Prepare repository for 0.40-DEV 8cc80fed9 releaser: Add release notes to /docs for release of 0.39 f7aa0d1c5 releaser: Bump versions for release of 0.39 42e48706a Merge commit '047c4188dfc854f658d16f1e4a9501f9c97a31c7' 76acab68b releaser: Prepare repository for 0.39-DEV d270600b0 releaser: Add release notes to /docs for release of 0.38.2 97be36992 releaser: Bump versions for release of 0.38.2 cd29b8b79 releaser: Prepare repository for 0.39-DEV 9983a4bdf releaser: Add release notes to /docs for release of 0.38.1 7774afd01 releaser: Bump versions for release of 0.38.1 b89157f20 releaser: Prepare repository for 0.39-DEV af4d0bf62 releaser: Add release notes to /docs for release of 0.38 ca98e7d4f releaser: Bump versions for release of 0.38 8b773833a Merge commit 'ed8bf081fdbf336e026517b7e1b123c039014ab5' 24202bb71 docs: Generate docshelper data 43d15975d Add .Site.IsServer 6f99d3d65 Merge commit '0a23baa6a90901f772c234107c4f12c16c76f4aa' 17487ccdd hugolib: Add Reset method to delete key from Scratch ccbf7a05c docs: Add docs for lang.Merge 5ad46d78e Merge commit '3886fc1fef6ac19d58b9ba1bb642d0c6c9a54031' ac403c280 docs: Add docs on the new front matter configuration 6066c60e6 Merge commit 'c0290655825e7bb36e13fb39f89d85b392cf1adc' ee605c7ae releaser: Prepare repository for 0.38-DEV 31a4de966 releaser: Add release notes to /docs for release of 0.37.1 9dd3dafe1 releaser: Bump versions for release of 0.37.1 141750aec releaser: Prepare repository for 0.38-DEV c9bb39bc3 releaser: Add release notes to /docs for release of 0.37 c7009f064 releaser: Bump versions for release of 0.37 9f727d916 Merge commit '900b5f6cfe5a377ef369d26cd700201be4cf6b06' 87fd97853 Merge commit '374d184e6747678364fd61f5faf328ec9205eb6b' 244deafc2 Fix typos in development contribution doc 608c80f72 Merge branch 'release-0.36.1' 0f8ffbd5c releaser: Prepare repository for 0.37-DEV 5028ee849 releaser: Add release notes to /docs for release of 0.36.1 9ccc7cb11 releaser: Bump versions for release of 0.36.1 3db31be07 Merge commit '9cc9bab46288d8d5f9fda7009c5f746258cec1b4' 9468246c5 Add "target" and "rel" parameters to figure shortcode 6d7fa89f9 releaser: Prepare repository for 0.37-DEV 1aec7ad81 releaser: Add release notes to /docs for release of 0.36 b522da389 releaser: Bump versions for release of 0.36 bb78bea13 docs: Add documentation for smart cropping etc. 930f16cae Merge commit 'c305e44f5f081e4436195923a4593e396f07cd49' 0e4c80ab9 releaser: Prepare repository for 0.36-DEV e0d4c6bcd releaser: Add release notes to /docs for release of 0.35 f4ac67eb3 releaser: Bump versions for release of 0.35 229a50b1f docs: Regenerate CLI docs 72958eb9c Merge commit '337d0c5f516ee085205e8abefdb7f87e6d33ca05' d998ca4c0 command: Remove undraft command 34a0052ef docs: Re-generate CLI docs fa04ff331 releaser: Prepare repository for 0.35-DEV 55e595720 releaser: Add release notes to /docs for release of 0.34 bf4d0e8fb releaser: Bump versions for release of 0.34 07673370e releaser: Prepare repository for 0.34-DEV 921ea8920 releaser: Add release notes to /docs for release of 0.33 3307f61bd releaser: Bump versions for release of 0.33 792a4410d Merge commit '3cf4300097610bb8b5bd0686d96d1df5db641895' 6d8a9f657 releaser: Prepare repository for 0.33-DEV e3afccf6f releaser: Add release notes to /docs for release of 0.32.4 7f29cb196 releaser: Bump versions for release of 0.32.4 baa364436 releaser: Prepare repository for 0.33-DEV 60c775166 releaser: Add release notes to /docs for release of 0.32.3 9cbab1803 releaser: Bump versions for release of 0.32.3 51823efee releaser: Prepare repository for 0.33-DEV 71e03684c releaser: Add release notes to /docs for release of 0.32.2 e18bf56fb releaser: Bump versions for release of 0.32.2 54aa93927 Merge commit 'eb738cd35cca1ffc68c5ed688dbe2a19108e8761' 5e8123994 releaser: Prepare repository for 0.33-DEV a55b78124 releaser: Add release notes to /docs for release of 0.32.1 7de53ff41 releaser: Bump versions for release of 0.32.1 e6e58785d releaser: Prepare repository for 0.33-DEV 58cf5009d releaser: Add release notes to /docs for release of 0.32 031719821 Merge commit 'f3cd083961f36dc96d05e98aaf67f650102bc757' b9183604b Add Pandoc support, refactor external helpers 3f9b9474c releaser: Prepare repository for 0.32-DEV 11e4ce514 releaser: Add release notes to /docs for release of 0.31.1 aebb1504b releaser: Bump versions for release of 0.31.1 d70b54d4a releaser: Prepare repository for 0.32-DEV cdc10468e releaser: Add release notes to /docs for release of 0.31 38bd41cab releaser: Bump versions for release of 0.31 1c581a11d Merge commit '30c0d485eaff6d70df1be0353911ddca485d52bf' b88e46d02 Merge commit '05e42bc643f1840ed2ad9c2eff82a269d1381683' a45ab174e Handle Taxonomy permalinks 9f27354f6 Add support for height argument to figure shortcode acc8e49c1 releaser: Prepare repository for 0.31-DEV 977266b19 releaser: Add release notes to /docs for release of 0.30.2 31b672844 releaser: Bump versions for release of 0.30.2 b8f6b72a8 Merge commit '325009c3fd4ac90021897b7e3e025c14e70ce162' c6e3dae71 releaser: Prepare repository for 0.31-DEV 2a3c7c7d9 releaser: Add release notes to /docs for release of 0.30.1 4c014117a releaser: Bump versions for release of 0.30.1 1da61da06 releaser: Prepare repository for 0.31-DEV 24864a46b releaser: Add release notes to /docs for release of 0.30 3011aa44a releaser: Bump versions for release of 0.30 bcbf3237b Merge commit 'ecf5e081b5540e69f4af330233f39a07baf53846' ab68b99ed Merge commit 'dae5a7c61cceeb0de59f2d755f63e453f71dd9b2' 0ae435725 tpl: Add errorf template function ac3fb3808 Change SummaryLength to be configurable (#3924) 3c0e4fa70 tpl: Add os.fileExists template function 9290f3983 Merge commit '9d68f695e782c6a83c77aff13317c7a22c694c98' 394e8b3f6 tpl: Add float template function c0c48c2ea releaser: Prepare repository for 0.30-DEV 0806d910b releaser: Add release notes to /docs for release of 0.29 0d1101836 releaser: Bump versions for release of 0.29 5d92b552b releaser: Prepare repository for 0.29-DEV 1ef521182 releaser: Add release notes to /docs for release of 0.28 c5441cff1 releaser: Bump versions for release of 0.28 46c2786f1 Merge commit '61c27b58b353c73772aae572c7d822fdfdf7791b' 6fed4008f Merge commit '30694a133a88d5f76a51d0372646e10cbeca7691' 595752e2f Merge commit '7a89dce53bfbd67a17442a8f9be8fa895fc4f9b1' af14cae0c Merge commit 'ba45da9d03056447e4873de13d4e0f8d658a769b' d0bb30963 releaser: Prepare repository for 0.28-DEV 469bf26aa releaser: Add release notes to /docs for release of 0.27.1 06ea00c12 releaser: Bump versions for release of 0.27.1 0668af58e releaser: Prepare repository for 0.28-DEV 4ce00c84d releaser: Add release notes to /docs for release of 0.27 68f318d0b releaser: Bump versions for release of 0.27 509ad6cc0 docs: Merge commit '1b4319be62ba071f79e90ef32dbe92eb893429f7' c625ae1ce docs: Document Related Content ecd5c24f5 docs: Merge commit '7d63a23b0c68d9cd7c7c09c2755619237bc03485' b97b84f9d Update docs versiona and README 2238f7a4a Merge commit 'ec4e6f9df2ab9ffdc62a3f59675369096e0d3f77' as 'docs' git-subtree-dir: docs git-subtree-split: cfe89ecbc2288a7270c23dbcc179733c8d978c4c
2018-07-18 09:04:57 +00:00
{{ range .Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</main>
{{< /code >}}
### `summary.html`
Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
{{< code file="layouts/_default/summary.html" download="summary.html" >}}
<article class="post">
<header>
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
<div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
</header>
{{ .Summary }}
<footer>
<a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
</footer>
</article>
{{< /code >}}
### `li.html`
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" }}`).
{{< code file="layouts/_default/li.html" download="li.html" >}}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{< /code >}}
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
[pagevars]: /variables/page/
[render]: /functions/render/
[single]: /templates/single-page-templates/
[spf]: http://spf13.com
[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
[summaries]: /content-management/summaries/
Squashed 'docs/' changes from f887bd7b..1d052b16 1d052b16 Update hosting-on-netlify.md 28b96bec Remove double brackets in Netlify hosting tutorial 373ed38b Update deployment instructions from hugo > 0.20 on Netlify 1bbb41ca Generate static assets on deploy in Nanobox tutorial 816d207f Add missing backtick in templates/views.md bf88e772 Add nanobox as a deployment option 9c37b4cc Change config's syntax order matching description d3cb05a7 Fix wrongly named default value of publishDir 4be85c54 Add link to showcase a theme setup via config file 46837195 Init and update of submodules in .gitlab-ci.yml 9e7c2827 Add CSS lang argument to code block 85aad56e Abstract the type in the lookup order 4e1e43e9 Fix broken Pygments url 65b4e79b Correct GitLab project pipelines URL 94af72b5 Fix .Data.Terms usage in taxonomy template example eb371e52 functions: Fix lang.NumFmt docs a745cd6c Fix layouts' folder name in template primer e181e637 Correct typo on GitHub pages guide (#151) 28698500 Remove HTML special chars from Windows install example 96b1f5b5 Remove not needed escape slashes in urls.md 2e05043f Add upgrade instructions using homebrew 2a14624d Fix alias in countrunes.md 5e26bb97 Update docker image for build/publish 01424887 List the internal templates a3ef5be9 Remove string concatenation from add (math) sample 43d12b44 Fix typo 89bafa49 Change to Asciidoc URI 4e14071e Removes an extra bracket (>) in single-page-templates.md 0938e423 Fix typo in http2 server push blog fac55121 Fix typo in deployment with rsync tutorial git-subtree-dir: docs git-subtree-split: 1d052b16a1290ada12f1e28c7c0c373f86741071
2017-09-05 16:09:40 +00:00
[taxonomylists]: /templates/taxonomy-templates/