TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-18 15:45:01 -04:00
Code Issues Packages Projects Releases Wiki Activity

Add nested section docs

Browse Source 
Fixes #36
This commit is contained in:
Bjørn Erik Pedersen 2017-11-22 09:22:50 +01:00
parent 783c3d6360
commit 149c2c1576
No known key found for this signature in database
GPG Key ID: 330E6E2BD4859D8F
3 changed files with 77 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
content/content-management/sections.md
View File

@ -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
| ├── _index.md // <- example.com/authors/
| ├── john-doe.md // <- example.com/authors/john-doe/
| └── jane-doe.md // <- example.com/authors/jane-doe/
└── events
| ├── _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/
```
## Section Page Variables and Methods
Also see [Page Variables](/variables/page/).
{{< readfile file="/content/readfiles/sectionvars.md" markdown="true" >}}
## 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/

20
content/readfiles/sectionvars.md Normal file
View File

@ -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.

15
content/variables/page.md
View File

@ -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.