Sections

Overview

A section is a top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a branch bundle. Section templates receive one or more page collections in context.

A typical site consists of one or more sections. For example:

content/
├── articles/             <-- section (top-level directory)
│   ├── 2022/
│   │   ├── article-1/
│   │   │   ├── cover.jpg
│   │   │   └── index.md
│   │   └── article-2.md
│   └── 2023/
│       ├── article-3.md
│       └── article-4.md
├── products/             <-- section (top-level directory)
│   ├── product-1/        <-- section (has _index.md file)
│   │   ├── benefits/     <-- section (has _index.md file)
│   │   │   ├── _index.md
│   │   │   ├── benefit-1.md
│   │   │   └── benefit-2.md
│   │   ├── features/     <-- section (has _index.md file)
│   │   │   ├── _index.md
│   │   │   ├── feature-1.md
│   │   │   └── feature-2.md
│   │   └── _index.md
│   └── product-2/        <-- section (has _index.md file)
│       ├── benefits/     <-- section (has _index.md file)
│       │   ├── _index.md
│       │   ├── benefit-1.md
│       │   └── benefit-2.md
│       ├── features/     <-- section (has _index.md file)
│       │   ├── _index.md
│       │   ├── feature-1.md
│       │   └── feature-2.md
│       └── _index.md
├── _index.md
└── about.md

The example above has two top-level sections: articles and products. None of the directories under articles are sections, while all of the directories under products are sections. A section within a section is a known as a nested section or subsection.

Explanation

Sections and non-sections behave differently.

With the file structure from the example above:

1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections.

2. The articles/2022 and articles/2023 directories do not have list pages; they are not sections.

3. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the .RegularPagesRecursive collection instead of the .Pages collection in the list template. See details.

4. All directories in the products section have list pages; each directory is a section.

Template selection

Hugo has a defined lookup order to determine which template to use when rendering a page. The lookup rules consider the top-level section name; subsection names are not considered when selecting a template.

With the file structure from the example above:

If you need to use a different template for a subsection, specify type and/or layout in front matter.

Ancestors and descendants

A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the example above:

content/products/product-1/benefits/benefit-1.md

The content file (benefit-1.md) has four ancestors: benefits, product-1, products, and the home page. This logical relationship allows us to use the .Parent and .Ancestors methods to traverse the site structure.

For example, use the .Ancestors method to render breadcrumb navigation.

<nav aria-label="breadcrumb" class="breadcrumb">
  <ol>
    {{ range .Ancestors.Reverse }}
      <li>
        <a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
      </li>
    {{ end }}
    <li class="active">
      <a aria-current="page" href="{{ .Permalink }}">{{ .LinkTitle }}</a>
    </li>
  </ol>
</nav>

With this CSS:

.breadcrumb ol {
  padding-left: 0;
}

.breadcrumb li {
  display: inline;
}

.breadcrumb li:not(:last-child)::after {
  content: "»";
}

Hugo renders this, where each breadcrumb is a link to the corresponding page:

Home » Products » Product 1 » Benefits » Benefit 1