hugo/content/templates/single-page-templates.md

108 lines
3.8 KiB
Markdown
Raw Normal View History

---
title: Single Page Templates
linktitle:
description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-04-06
categories: [templates]
keywords: [page]
menu:
docs:
parent: "templates"
weight: 60
weight: 60
sections_weight: 60
draft: false
aliases: [/layout/content/]
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`
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 12:09:40 -04:00
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 >}}
## Example Single Page Templates
Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates.
### `post/single.html`
This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter.
{{< code file="layouts/post/single.html" download="single.html" >}}
{{ define "main" }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
<div>
<article id="content">
{{ .Content }}
</article>
</div>
</section>
<aside id="meta">
<div>
<section>
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
<h5 id="wordcount"> {{ .WordCount }} Words </h5>
</section>
{{ with .Params.topics }}
<ul id="topics">
{{ range . }}
<li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
{{ end }}
{{ with .Params.tags }}
<ul id="tags">
{{ range . }}
<li> <a href="{{ "tags" | absURL }}{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
{{ end }}
</div>
<div>
{{ with .PrevInSection }}
<a class="previous" href="{{.Permalink}}"> {{.Title}}</a>
{{ end }}
{{ with .NextInSection }}
<a class="next" href="{{.Permalink}}"> {{.Title}}</a>
{{ end }}
</div>
</aside>
{{ end }}
{{< /code >}}
To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes].
[archetypes]: /content-management/archetypes/
[base templates]: /templates/base/
[config]: /getting-started/configuration/
[content type]: /content-management/types/
[directory structure]: /getting-started/directory-structure/
[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
[`.Format` function]: /functions/format/
[front matter]: /content-management/front-matter/
[pagetaxonomy]: /templates/taxonomy-templates/#displaying-a-single-piece-of-content-s-taxonomies
[pagevars]: /variables/page/
[partials]: /templates/partials/
[section]: /content-management/sections/
[site variables]: /variables/site/
[spf13]: http://spf13.com/
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 12:09:40 -04:00
[`with`]: /functions/with/