Add nested section docs

Fixes #36

content/content-management/sections.md

@@ -1,7 +1,7 @@
 ---
 title: Content Sections
 linktitle: Sections
-description: Hugo supports content sections, which according to Hugo's default behavior, will reflect the structure of the rendered website.
+description: "Hugo generates a **section tree** that matches your content."
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
@@ -17,53 +17,70 @@ aliases: [/content/sections/]
 toc: true
 ---
 
+
+## Nested Sections
+
+The sections can be nested as deeply as you need.
+
+```bash
+blog
+├── funny-cats
+│   └── kittens
+│       └── _index.md
+└── tech
+    └── _index.md
+```
+
+
+**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).** 
+
+
 {{% note %}}
-This section is not updated with the new nested sections support in Hugo 0.24, see https://github.com/gohugoio/hugoDocs/issues/36
+When we talk about a **section** in correlation with template selection, it is currently always the root section only (`/blog/funny/mypost/ => blog`). 
+
+It is currently not possible to add a specific layout for one of the sub-sections.
 {{% /note %}}
-{{% todo %}}
-See above
-{{% /todo %}}
 
-Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site (see [directory structure][]).
 
-Following this pattern, Hugo uses the top level of your content organization as the content **section**.
+## Example: Breadcrumb Navigation
 
-The following example shows a content directory structure for a website that has three sections: "authors," "events," and "posts":
+With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation:
 
+
+```html
+<ul>
+  {{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
+</ul>
+{{ define "breadcrumbnav" }}
+{{ if .p1.Parent }}
+{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 )  }}
+{{ else if not .p1.IsHome }}
+{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 )  }}
+{{ end }}
+<li>
+  {{ if eq .p1 .p2 }}
+  {{ .p1.Title }}
+  {{ else }}
+  <a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a>
+  {{ end }}
+</li>
+{{ end }}
 ```
-.
+
-└── content
+
-    ├── authors
+## Section Page Variables and Methods
-    |   ├── _index.md     // <- example.com/authors/
+
-    |   ├── john-doe.md   // <- example.com/authors/john-doe/
+Also see [Page Variables](/variables/page/).
-    |   └── jane-doe.md   // <- example.com/authors/jane-doe/
+
-    └── events
+{{< readfile file="/content/readfiles/sectionvars.md" markdown="true" >}}
-    |   ├── _index.md     // <- example.com/events/
-    |   ├── event-1.md    // <- example.com/events/event-1/
-    |   ├── event-2.md    // <- example.com/events/event-2/
-    |   └── event-3.md    // <- example.com/events/event-3/
-    └── posts
-    |   ├── _index.md    // <- example.com/posts/
-    |   ├── post-1.md    // <- example.com/posts/post-1/
-    |   ├── post-2.md    // <- example.com/posts/post-2/
-    |   ├── post-3.md    // <- example.com/posts/post-3/
-    |   ├── post-4.md    // <- example.com/posts/post-4/
-    |   └── post-5.md    // <- example.com/posts/post-5/
-```
 
 ## Content Section Lists
 
 Hugo will automatically create pages for each section root that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered.
 
-As of Hugo v0.18, section pages can also have a content file and front matter. These section content files must be placed in their corresponding section folder and named `_index.md` in order for Hugo to correctly render the front matter and content.
-
-{{% warning "`index.md` vs `_index.md`" %}}
-Hugo themes developed before v0.18 often used an `index.md`(i.e., without the leading underscore [`_`]) in a content section as a hack to emulate the behavior of `_index.md`. The hack may work...*sometimes*; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is **strongly advised** to use `_index.md` as content for your section index pages. **Note:** `_index.md`'s layout, as representative of a section, is a [list page template](/templates/section-templates/) and *not* a [single page template](/templates/single-page-templates/). If you want to alter the new default behavior for `_index.md`, configure `disableKinds` accordingly in your [site's configuration](/getting-started/configuration/).
-{{% /warning %}}
-
 ## Content *Section* vs Content *Type*
 
-By default, everything created within a section will use the [content type][] that matches the section name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content type. If you are using an [archetype][] for your posts section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
+By default, everything created within a section will use the [content type][] that matches the root section name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content type. If you are using an [archetype][] for your posts section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
 
 [archetype]: /content-management/archetypes/
 [content type]: /content-management/types/

content/readfiles/sectionvars.md

@@ -0,0 +1,20 @@
+.CurrentSection
+: the page's current section. The value can be the page itself if it is a section or the homepage.
+
+.InSection $anotherPage
+: whether the given page is in the current section. Note that this will always return false for pages that are not either regular, home or section pages.
+
+.IsAncestor $anotherPage
+: whether the current page is an ancestor of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
+
+.IsDescendant $anotherPage
+: whether the current page is a descendant of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
+
+.Parent
+: a section's parent section or a page's section.
+
+.Section
+: the [section](/content-management/sections/) this content belongs to. **Note:** For nested sections, this is the first path element in the directory, for example, `/blog/funny/mypost/ => blog`.
+
+.Sections
+: the [sections](/content-management/sections/) below this content.

content/variables/page.md

@@ -32,9 +32,6 @@ See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables.
 `.Content`
 : the content itself, defined below the front matter.
 
-`.CurrentSection`
-: the page's current section. The value can be the page itself if it is a section or the homepage.
-
 `.Data`
 : the data specific to this type of page.
 
@@ -148,12 +145,6 @@ http://remarkjs.com)
 : returns the relative permalink for a given reference (e.g., `RelRef
 "sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
 
-`.Section`
-: the [section](/content-management/sections/) this content belongs to.
-
-`.Sections`
-: the [sections](/content-management/sections/) below this content.
-
 `.Site`
 : see [Site Variables](/variables/site/).
 
@@ -187,6 +178,12 @@ http://remarkjs.com)
 `.WordCount`
 : the number of words in the content.
 
+## Section Variables and Methods
+
+Also see [Sections](/content-management/sections/).
+
+{{< readfile file="/content/readfiles/sectionvars.md" markdown="true" >}}
+
 ## Page-level Params
 
 Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.