diff --git a/content/content-management/sections.md b/content/content-management/sections.md index 411379224..855bd1bc0 100644 --- a/content/content-management/sections.md +++ b/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 + +{{ 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 }} +
  • + {{ if eq .p1 .p2 }} + {{ .p1.Title }} + {{ else }} + {{ .p1.Title }} + {{ end }} +
    • +{{ 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/ diff --git a/content/readfiles/sectionvars.md b/content/readfiles/sectionvars.md new file mode 100644 index 000000000..c0756e7d1 --- /dev/null +++ b/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. diff --git a/content/variables/page.md b/content/variables/page.md index 41d3e4462..09b9635bc 100644 --- a/content/variables/page.md +++ b/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.