From 19e99c957b86631e612b64d2929e8e93c1b25333 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Fri, 9 Mar 2018 16:20:26 -0500 Subject: [PATCH 01/19] Add Section definition Fixes https://github.com/gohugoio/hugoDocs/issues/409 --- content/content-management/sections.md | 44 ++++++++++++++++---------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/content/content-management/sections.md b/content/content-management/sections.md index 0e167d143..9e842b929 100644 --- a/content/content-management/sections.md +++ b/content/content-management/sections.md @@ -17,36 +17,49 @@ aliases: [/content/sections/] toc: true --- +A **Section** is a collection of pages that gets defined based on the +organization structure under the `content/` directory. + +By default, all the **first-level** directories under `content/` form their own +sections (**root sections**). + +If a user needs to define a section `foo` at a deeper level, they need to create +a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch +bundles] for more information). + +{{% note %}} +A **section** cannot be defined or overridden by a front matter parameter -- it +is strictly derived from the content organization structure. +{{% /note %}} ## Nested Sections The sections can be nested as deeply as you need. ```bash -blog -├── funny-cats -│   └── kittens -│   └── _index.md -└── tech - └── _index.md +content +└── blog <-- Section, because first-level dir under content/ + ├── funny-cats + │   ├── mypost.md + │   └── kittens <-- Section, because contains _index.md + │   └── _index.md + └── tech <-- Section, because contains _index.md + └── _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`).** - +**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 %}} -When we talk about a **section** in correlation with template selection, it is currently always the root section only (`/blog/funny/mypost/ => blog`). +When we talk about a **section** in correlation with template selection, it is +currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`). If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter. {{% /note %}} - ## Example: Breadcrumb Navigation 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: - {{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}