mirror of
https://github.com/tiennm99/hugoDocs.git
synced 2026-10-15 14:16:29 +00:00
Move list and homepage content to list templates page
Closes rdwatters/hugo-docs-concept#49
This commit is contained in:
Ryan Watters committed
1 parent
e6511dff2b
commit
109a6a592d
3 files changed
+113
-158
No files matched your search
@@ -33,7 +33,7 @@ You can limit the number of matches in the list with a third parameter. The foll
|
|||||||
<!-- returns ["<h2 id="#foo">Foo</h2>"] -->
|
<!-- returns ["<h2 id="#foo">Foo</h2>"] -->
|
||||||
```
|
```
|
||||||
|
|
||||||
<!-- Removed per request of @bep -->
|
<!-- Removed per request of @bep: https://github.com/spf13/hugo/issues/3188 -->
|
||||||
<!-- ## `findRE` Example: Building a Table of Contents
|
<!-- ## `findRE` Example: Building a Table of Contents
|
||||||
|
|
||||||
`findRE` allows us to build an automatically generated table of contents that could be used for a simple scrollspy if you don't want to use [Hugo's native .TableOfContents feature][toc]. The following shows how this could be done in a [partial template][partials]:
|
`findRE` allows us to build an automatically generated table of contents that could be used for a simple scrollspy if you don't want to use [Hugo's native .TableOfContents feature][toc]. The following shows how this could be done in a [partial template][partials]:
|
||||||
|
|||||||
@@ -57,164 +57,7 @@ used by Hugo when generating your website. You can write these files in YAML, JS
|
|||||||
: stores all the static content for your future website: images, CSS, JavaScript, etc. Note that when Hugo build your site, all assets inside your static directory are copied over as-is.
|
: stores all the static content for your future website: images, CSS, JavaScript, etc. Note that when Hugo build your site, all assets inside your static directory are copied over as-is.
|
||||||
|
|
||||||
|
|
||||||
## Example Hugo Project Directory
|
|
||||||
|
|
||||||
The following is an example of a typical Hugo project directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
.
|
|
||||||
├── config.toml
|
|
||||||
├── archetypes
|
|
||||||
| └── default.md
|
|
||||||
├── content
|
|
||||||
| ├── post
|
|
||||||
| | ├── _index.md
|
|
||||||
| | ├── post-01.md
|
|
||||||
| | └── post-02.md
|
|
||||||
| └── quote
|
|
||||||
| | ├── quote-01.md
|
|
||||||
| | └── quote-02.md
|
|
||||||
├── data
|
|
||||||
├── i18n
|
|
||||||
├── layouts
|
|
||||||
| ├── _default
|
|
||||||
| | ├── single.html
|
|
||||||
| | └── list.html
|
|
||||||
| ├── partials
|
|
||||||
| | ├── header.html
|
|
||||||
| | └── footer.html
|
|
||||||
| ├── taxonomies
|
|
||||||
| | ├── category.html
|
|
||||||
| | ├── post.html
|
|
||||||
| | ├── quote.html
|
|
||||||
| | └── tag.html
|
|
||||||
| ├── post
|
|
||||||
| | ├── li.html
|
|
||||||
| | ├── single.html
|
|
||||||
| | └── summary.html
|
|
||||||
| ├── quote
|
|
||||||
| | ├── li.html
|
|
||||||
| | ├── single.html
|
|
||||||
| | └── summary.html
|
|
||||||
| ├── shortcodes
|
|
||||||
| | ├── img.html
|
|
||||||
| | ├── vimeo.html
|
|
||||||
| | └── youtube.html
|
|
||||||
| ├── index.html
|
|
||||||
| └── sitemap.xml
|
|
||||||
├── themes
|
|
||||||
| ├── hyde
|
|
||||||
| └── doc
|
|
||||||
└── static
|
|
||||||
├── css
|
|
||||||
├── images
|
|
||||||
└── js
|
|
||||||
```
|
|
||||||
|
|
||||||
The above directory structure tells us a lot about this project.
|
|
||||||
|
|
||||||
The rendered website
|
|
||||||
|
|
||||||
* has two different [types of content][types]: `posts` and `quotes`.
|
|
||||||
* applies two different [taxonomies][] to the content: `categories` and `tags`
|
|
||||||
* displays content in 3 different views: a list, a summary, and a full-page view
|
|
||||||
|
|
||||||
## Homepage and List Page Content
|
|
||||||
|
|
||||||
Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files---i.e. `_index.md`---that contains page metadata (i.e., front matter) and content. This model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) also have access to all [page variables][pagevars].
|
|
||||||
|
|
||||||
Using the above example, let's assume you have the following in `content/post/_index.md`:
|
|
||||||
|
|
||||||
{{% code file="content/post/_index.md" %}}
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
title: My Golang Journey
|
|
||||||
date: 2017-03-23
|
|
||||||
publishdate: 2017-03-24
|
|
||||||
---
|
|
||||||
|
|
||||||
I decided to start learning Golang in March 2017.
|
|
||||||
|
|
||||||
Follow my journey through this new blog.
|
|
||||||
```
|
|
||||||
{{% /code %}}
|
|
||||||
|
|
||||||
You can now access this `_index.md` content in a [list template][lists]:
|
|
||||||
|
|
||||||
{{% code file="layouts/_default/list.html" %}}
|
|
||||||
```html
|
|
||||||
{{ define "main" }}
|
|
||||||
<main class="main">
|
|
||||||
<article>
|
|
||||||
<header>
|
|
||||||
<h1>{{.Title}}</h1>
|
|
||||||
</header>
|
|
||||||
{{.Content}}
|
|
||||||
</article>
|
|
||||||
<ul class="section-contents">
|
|
||||||
{{ range .Data.Pages }}
|
|
||||||
<li>
|
|
||||||
<a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a
|
|
||||||
</li>
|
|
||||||
{{ end }}
|
|
||||||
</ul>
|
|
||||||
</main>
|
|
||||||
{{ end }}
|
|
||||||
```
|
|
||||||
{{% /code %}}
|
|
||||||
|
|
||||||
This will output the following HTML:
|
|
||||||
|
|
||||||
{{% code file="yoursite.com/post/index.html" copy="false" %}}
|
|
||||||
```html
|
|
||||||
<!--all your baseof.html code-->
|
|
||||||
<main class="main">
|
|
||||||
<article>
|
|
||||||
<header>
|
|
||||||
<h1>My Golang Journey</h1>
|
|
||||||
</header>
|
|
||||||
<p>I decided to start learning Golang in March 2017.</p>
|
|
||||||
<p>Follow my journey through this new blog.</p>
|
|
||||||
</article>
|
|
||||||
<ul class="section-contents">
|
|
||||||
<li><a href="/post/post-01/">Post 1</a></li>
|
|
||||||
<li><a href="/post/post-02/">Post 2</a></li>
|
|
||||||
</ul>
|
|
||||||
</main>
|
|
||||||
<!--all your other baseof.html code-->
|
|
||||||
```
|
|
||||||
{{% /code %}}
|
|
||||||
|
|
||||||
### List Pages Without `_index.md`
|
|
||||||
|
|
||||||
You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a [list template][lists], the page will be created but with no `{{.Content}}` and only the default values for `.Title` etc.
|
|
||||||
|
|
||||||
Using this same `layouts/_default/list.html` template and applying it to the the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from:
|
|
||||||
|
|
||||||
{{% code file="yoursite.com/quote/index.html" copy="false" %}}
|
|
||||||
```html
|
|
||||||
<!--baseof.html code-->
|
|
||||||
<main class="main">
|
|
||||||
<article>
|
|
||||||
<header>
|
|
||||||
<h1>Quotes</h1>
|
|
||||||
</header>
|
|
||||||
</article>
|
|
||||||
<ul class="section-contents">
|
|
||||||
<li><a href="https://yoursite.com/quote/quotes-01/">Quote 1</a></li>
|
|
||||||
<li><a href="https://yoursite.com/quote/quotes-02/">Quote 2</a></li>
|
|
||||||
</ul>
|
|
||||||
</main>
|
|
||||||
<!--baseof.html code-->
|
|
||||||
```
|
|
||||||
{{% /code %}}
|
|
||||||
|
|
||||||
{{% note %}}
|
|
||||||
The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/).
|
|
||||||
{{% /note %}}
|
|
||||||
|
|
||||||
[archetypes]: /content-management/archetypes/
|
[archetypes]: /content-management/archetypes/
|
||||||
[bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/
|
|
||||||
[configuration directives]: /getting-started/configuration/#all-variables-yaml
|
[configuration directives]: /getting-started/configuration/#all-variables-yaml
|
||||||
[`content`]: /content-management/organization/
|
[`content`]: /content-management/organization/
|
||||||
[content section]: /content-management/sections/
|
[content section]: /content-management/sections/
|
||||||
|
|||||||
@@ -44,6 +44,117 @@ Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxte
|
|||||||
1. `layouts/_default/taxonomy.html`
|
1. `layouts/_default/taxonomy.html`
|
||||||
2. `themes/<THEME>/layouts/_default/taxonomy.html`
|
2. `themes/<THEME>/layouts/_default/taxonomy.html`
|
||||||
|
|
||||||
|
## Adding Content to List Pages
|
||||||
|
|
||||||
|
Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files---i.e. `_index.md`---that contains page metadata (i.e., front matter) and content. This model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) also have access to all [page variables][pagevars].
|
||||||
|
|
||||||
|
### Example Project Directory
|
||||||
|
|
||||||
|
The following is an example of a typical Hugo project directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
.
|
||||||
|
├── config.toml
|
||||||
|
├── content
|
||||||
|
| ├── post
|
||||||
|
| | ├── _index.md
|
||||||
|
| | ├── post-01.md
|
||||||
|
| | └── post-02.md
|
||||||
|
| └── quote
|
||||||
|
| | ├── quote-01.md
|
||||||
|
| | └── quote-02.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Using the above example, let's assume you have the following in `content/post/_index.md`:
|
||||||
|
|
||||||
|
{{% code file="content/post/_index.md" %}}
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
title: My Golang Journey
|
||||||
|
date: 2017-03-23
|
||||||
|
publishdate: 2017-03-24
|
||||||
|
---
|
||||||
|
|
||||||
|
I decided to start learning Golang in March 2017.
|
||||||
|
|
||||||
|
Follow my journey through this new blog.
|
||||||
|
```
|
||||||
|
{{% /code %}}
|
||||||
|
|
||||||
|
You can now access this `_index.md`'s' content in your list template:
|
||||||
|
|
||||||
|
{{% code file="layouts/_default/list.html" %}}
|
||||||
|
```html
|
||||||
|
{{ define "main" }}
|
||||||
|
<main class="main">
|
||||||
|
<article>
|
||||||
|
<header>
|
||||||
|
<h1>{{.Title}}</h1>
|
||||||
|
</header>
|
||||||
|
{{.Content}}
|
||||||
|
</article>
|
||||||
|
<ul class="section-contents">
|
||||||
|
{{ range .Data.Pages }}
|
||||||
|
<li>
|
||||||
|
<a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a
|
||||||
|
</li>
|
||||||
|
{{ end }}
|
||||||
|
</ul>
|
||||||
|
</main>
|
||||||
|
{{ end }}
|
||||||
|
```
|
||||||
|
{{% /code %}}
|
||||||
|
|
||||||
|
This above will output the following HTML:
|
||||||
|
|
||||||
|
{{% code file="yoursite.com/post/index.html" copy="false" %}}
|
||||||
|
```html
|
||||||
|
<!--all your baseof.html code-->
|
||||||
|
<main class="main">
|
||||||
|
<article>
|
||||||
|
<header>
|
||||||
|
<h1>My Golang Journey</h1>
|
||||||
|
</header>
|
||||||
|
<p>I decided to start learning Golang in March 2017.</p>
|
||||||
|
<p>Follow my journey through this new blog.</p>
|
||||||
|
</article>
|
||||||
|
<ul class="section-contents">
|
||||||
|
<li><a href="/post/post-01/">Post 1</a></li>
|
||||||
|
<li><a href="/post/post-02/">Post 2</a></li>
|
||||||
|
</ul>
|
||||||
|
</main>
|
||||||
|
<!--all your other baseof.html code-->
|
||||||
|
```
|
||||||
|
{{% /code %}}
|
||||||
|
|
||||||
|
### List Pages Without `_index.md`
|
||||||
|
|
||||||
|
You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a [list template][lists], the page will be created but with no `{{.Content}}` and only the default values for `.Title` etc.
|
||||||
|
|
||||||
|
Using this same `layouts/_default/list.html` template and applying it to the the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from:
|
||||||
|
|
||||||
|
{{% code file="yoursite.com/quote/index.html" copy="false" %}}
|
||||||
|
```html
|
||||||
|
<!--baseof.html code-->
|
||||||
|
<main class="main">
|
||||||
|
<article>
|
||||||
|
<header>
|
||||||
|
<h1>Quotes</h1>
|
||||||
|
</header>
|
||||||
|
</article>
|
||||||
|
<ul class="section-contents">
|
||||||
|
<li><a href="https://yoursite.com/quote/quotes-01/">Quote 1</a></li>
|
||||||
|
<li><a href="https://yoursite.com/quote/quotes-02/">Quote 2</a></li>
|
||||||
|
</ul>
|
||||||
|
</main>
|
||||||
|
<!--baseof.html code-->
|
||||||
|
```
|
||||||
|
{{% /code %}}
|
||||||
|
|
||||||
|
{{% note %}}
|
||||||
|
The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/).
|
||||||
|
{{% /note %}}
|
||||||
|
|
||||||
|
|
||||||
## Example List Templates
|
## Example List Templates
|
||||||
|
|
||||||
@@ -446,6 +557,7 @@ Using `first` and `where` together can be very powerful:
|
|||||||
{{% /code %}}
|
{{% /code %}}
|
||||||
|
|
||||||
|
|
||||||
|
[bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/
|
||||||
[directorystructure]: /getting-started/directory-structure/
|
[directorystructure]: /getting-started/directory-structure/
|
||||||
[homepage]: /templates/homepage/
|
[homepage]: /templates/homepage/
|
||||||
[homepage]: /templates/homepage/
|
[homepage]: /templates/homepage/
|
||||||
|
|||||||
Reference in new issue
Block a user