sections.md (3986B)
1 ---
2 title: Content Sections
3 linktitle: Sections
4 description: "Hugo generates a **section tree** that matches your content."
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-02-01
8 categories: [content management]
9 keywords: [lists,sections,content types,organization]
10 menu:
11 docs:
12 parent: "content-management"
13 weight: 50
14 weight: 50 #rem
15 draft: false
16 aliases: [/content/sections/]
17 toc: true
18 ---
19
20 A **Section** is a collection of pages that gets defined based on the
21 organization structure under the `content/` directory.
22
23 By default, all the **first-level** directories under `content/` form their own
24 sections (**root sections**) provided they constitute [Branch Bundles][branch bundles].
25 Directories which are just [Leaf Bundles][leaf bundles] do *not* form
26 their own sections, despite being first-level directories.
27
28 If a user needs to define a section `foo` at a deeper level, they need to create
29 a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles]
30 for more information).
31
32
33 {{% note %}}
34 A **section** cannot be defined or overridden by a front matter parameter -- it
35 is strictly derived from the content organization structure.
36 {{% /note %}}
37
38 ## Nested Sections
39
40 The sections can be nested as deeply as you need.
41
42 ```bash
43 content
44 └── blog <-- Section, because first-level dir under content/
45 ├── funny-cats
46 │ ├── mypost.md
47 │ └── kittens <-- Section, because contains _index.md
48 │ └── _index.md
49 └── tech <-- Section, because contains _index.md
50 └── _index.md
51 ```
52
53 **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`).**
54
55 {{% note %}}
56 When we talk about a **section** in correlation with template selection, it is
57 currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`).
58
59 If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter.
60 {{% /note %}}
61
62 ## Example: Breadcrumb Navigation
63
64 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:
65
66 {{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}
67 <ol class="nav navbar-nav">
68 {{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
69 </ol>
70 {{ define "breadcrumbnav" }}
71 {{ if .p1.Parent }}
72 {{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) }}
73 {{ else if not .p1.IsHome }}
74 {{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }}
75 {{ end }}
76 <li{{ if eq .p1 .p2 }} class="active"{{ end }}>
77 <a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a>
78 </li>
79 {{ end }}
80 {{< /code >}}
81
82 ## Section Page Variables and Methods
83
84 Also see [Page Variables](/variables/page/).
85
86 {{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
87
88 ## Content Section Lists
89
90 Hugo will automatically create pages for each *root section* 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.
91
92 ## Content *Section* vs Content *Type*
93
94 By default, everything created within a section will use the [content `type`][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`.
95
96 [archetype]: /content-management/archetypes/
97 [content type]: /content-management/types/
98 [directory structure]: /getting-started/directory-structure/
99 [section templates]: /templates/section-templates/
100 [leaf bundles]: /content-management/page-bundles/#leaf-bundles
101 [branch bundles]: /content-management/page-bundles/#branch-bundles