hugo/docs/content/en/content-management/sections.md

title	description	categories	keywords	menu	weight	toc	aliases
Sections	Organize content into sections.	content management	lists sections content types organization	docs parent weight content-management 120	120	true	/content/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.

{{% note %}} Although top-level directories without _index.md files are sections, we recommend creating _index.md files in all sections. {{% /note %}}

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.

	Sections	Non-sections
Directory names become URL segments	✔️	✔️
Have logical ancestors and descendants	✔️	❌
Have list pages	✔️	❌

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:

Content directory	List page template
content/products	layouts/products/list.html
content/products/product-1	layouts/products/list.html
content/products/product-1/benefits	layouts/products/list.html

Content directory	Single page template
content/products	layouts/products/single.html
content/products/product-1	layouts/products/single.html
content/products/product-1/benefits	layouts/products/single.html

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.

{{< code file=layouts/partials/breadcrumb.html >}}

{{ range .Ancestors.Reverse }}
1. {{ .LinkTitle }}
{{ end }}
2. {{ .LinkTitle }}

{{< /code >}}

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