docs: Add sections on node now being a page

Updates #2297

docs/content/content/sections.md

@@ -36,6 +36,8 @@ Hugo will automatically create pages for each section root that list all
 of the content in that section. See [List Templates](/templates/list/)
 for details on customizing the way they appear.
 
+Section pages can also have a content file and frontmatter, see [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}).
+
 ## Sections and Types
 
 By default everything created within a section will use the content type

docs/content/overview/source-directory.md

@@ -95,3 +95,32 @@ This directory structure tells us a lot about this site:
 1. The website intends to have two different types of content: *posts* and *quotes*.
 2. It will also apply two different taxonomies to that content: *categories* and *tags*.
 3. It will be displaying content in 3 different views: a list, a summary and a full page view.
+
+## Content for home page and other list pages
+
+Since Hugo 0.18, "everything" is a `Page` that can have content and metadata, like `.Params`, attached to it -- and share the same set of [page variables](/templates/variables/).
+
+To add content and frontmatter to the home page, a section, a taxonomy or a taxonomy terms listing, add a markdown file with the base name `_index` on the relevant place on the file system.
+
+For the default Markdown content, the filename will be `_index.html`. 
+
+Se the example directory tree below. 
+
+**Note that you don't have to create `_index` file for every section, taxonomy and similar, a default page will be created if not present, but with no content an default values for `.Title` etc.**
+
+```bash
+└── content
+    ├── _index.md
+    ├── categories
+    │   ├── _index.md
+    │   └── photo
+    │       └── _index.md
+    ├── post
+    │   ├── _index.md
+    │   └── firstpost.md
+    └── tags
+        ├── _index.md
+        └── hugo
+            └── _index.md
+```
+  

docs/content/taxonomies/usage.md

@@ -2,6 +2,7 @@
 lastmod: 2015-12-23
 date: 2014-05-26
 linktitle: Usage
+toc: true
 menu:
   main:
     parent: taxonomy
@@ -68,7 +69,7 @@ but will still titleize the values for titles and normalize them in URLs.
 Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages,
 you will need to pass the taxonomy values through the `urlize` template function.
 
-### Front Matter Example (in TOML)
+## Front Matter Example (in TOML)
 
 ```toml
 +++
@@ -81,7 +82,7 @@ project_url = "https://github.com/spf13/hugo"
 +++
 ```
 
-### Front Matter Example (in JSON)
+## Front Matter Example (in JSON)
 
 ```json
 {
@@ -102,3 +103,7 @@ project_url = "https://github.com/spf13/hugo"
     "project_url": "https://github.com/spf13/hugo"
 }
 ```
+
+## Add content file with frontmatter
+
+See [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}).

docs/content/templates/functions.md

@@ -989,3 +989,17 @@ responses of APIs.
     {{ $resp.content | base64Decode | markdownify }}
 
 The response of the GitHub API contains the base64-encoded version of the [README.md](https://github.com/spf13/hugo/blob/master/README.md) in the Hugo repository. Now we can decode it and parse the Markdown. The final output will look similar to the rendered version on GitHub.
+
+
+## .Site.GetPage
+Every `Page` as a `Kind` attribute that shows what kind of page it is. While this attribute can be used to list pages of a certain `kind` using `where`, often it can be useful to fetch a single page by its path.
+
+GetPage looks up an index page of a given `Kind` and `path`. This method may support regular pages in the future, but currently it is a convenient way of getting the index pages such as the home page or a section from a template:
+
+```
+ {{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}
+ ```
+ 
+This method wil return `nil` when no page could be found, so the above will not print anything if the blog section isn't found.
+
+The valid page kinds are: *home, section, taxonomy and taxonomyTerm.*

docs/content/templates/homepage.md

@@ -28,6 +28,8 @@ In addition to the standard page variables, the homepage has access to
 all site content accessible from `.Data.Pages`. Details on how to use the
 list of pages can be found in the [Lists Template](/templates/list/).
 
+Note that a home page can also have a content file with frontmatter,  see [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}).
+
 ## Which Template will be rendered?
 Hugo uses a set of rules to figure out which template to use when
 rendering a specific page.

docs/content/templates/list.md

@@ -46,6 +46,7 @@ A Section will be rendered at /`SECTION`/ (e.g. http://spf13.com/project/)
 * /themes/`THEME`/layouts/\_default/section.html
 * /themes/`THEME`/layouts/\_default/list.html
 
+Note that a sections list page can also have a content file with frontmatter,  see [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}).
 
 ### Taxonomy Lists
 
@@ -58,6 +59,8 @@ A Taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g.&nbsp;http://spf13.com/top
 * /themes/`THEME`/layouts/\_default/taxonomy.html
 * /themes/`THEME`/layouts/\_default/list.html
 
+Note that a taxonomy list page can also have a content file with frontmatter,  see [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}).
+
 ### Section RSS
 
 A Section’s RSS will be rendered at /`SECTION`/index.xml (e.g.&nbsp;http://spf13.com/project/index.xml)

docs/content/templates/terms.md

@@ -20,6 +20,8 @@ A unique template is needed to create a list of the terms for a given
 taxonomy. This is different from the [list template](/templates/list/)
 as that template is a list of content, whereas this is a list of meta data.
 
+Note that a taxonomy terms page can also have a content file with frontmatter,  see [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}).
+
 ## Which Template will be rendered?
 Hugo uses a set of rules to figure out which template to use when
 rendering a specific page.