github.com/jbramsden/hugo@v0.47.1/docs/content/en/content-management/sections.md (about)

     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**).
    25  
    26  If a user needs to define a section `foo` at a deeper level, they need to create
    27  a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles]
    28  for more information).
    29  
    30  
    31  {{% note %}}
    32  A **section** cannot be defined or overridden by a front matter parameter -- it
    33  is strictly derived from the content organization structure.
    34  {{% /note %}}
    35  
    36  ## Nested Sections
    37  
    38  The sections can be nested as deeply as you need.
    39  
    40  ```bash
    41  content
    42  └── blog        <-- Section, because first-level dir under content/
    43      ├── funny-cats
    44      │   ├── mypost.md
    45      │   └── kittens         <-- Section, because contains _index.md
    46      │       └── _index.md
    47      └── tech                <-- Section, because contains _index.md
    48          └── _index.md
    49  ```
    50  
    51  **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`).**
    52  
    53  {{% note %}}
    54  When we talk about a **section** in correlation with template selection, it is
    55  currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`).
    56  
    57  If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter.
    58  {{% /note %}}
    59  
    60  ## Example: Breadcrumb Navigation
    61  
    62  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:
    63  
    64  {{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}
    65  <ol  class="nav navbar-nav">
    66    {{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
    67  </ol>
    68  {{ define "breadcrumbnav" }}
    69  {{ if .p1.Parent }}
    70  {{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 )  }}
    71  {{ else if not .p1.IsHome }}
    72  {{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 )  }}
    73  {{ end }}
    74  <li{{ if eq .p1 .p2 }} class="active"{{ end }}>
    75    <a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a>
    76  </li>
    77  {{ end }}
    78  {{< /code >}}
    79  
    80  ## Section Page Variables and Methods
    81  
    82  Also see [Page Variables](/variables/page/).
    83  
    84  {{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
    85  
    86  ## Content Section Lists
    87  
    88  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.
    89  
    90  ## Content *Section* vs Content *Type*
    91  
    92  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`.
    93  
    94  [archetype]: /content-management/archetypes/
    95  [content type]: /content-management/types/
    96  [directory structure]: /getting-started/directory-structure/
    97  [section templates]: /templates/section-templates/
    98  [branch bundles]: /content-management/page-bundles/#branch-bundles