Sections

Sections are directories that group related content. They require an _index.md file.

Creating a Section

content/
└── blog/
    ├── _index.md     # Section index → /blog/
    ├── first.md      # Page → /blog/first/
    └── second.md     # Page → /blog/second/

Section Index

Every section needs an _index.md:

+++
title = "Blog"
description = "Latest articles"
sort_by = "date"
+++

Welcome to my blog.

Front Matter

Cascade

A section's [cascade] table sets front matter defaults for every page and section below it. A page's own front matter always wins, and deeper cascades override shallower ones. The section declaring the cascade is not affected.

+++
title = "Blog"

[cascade]
template = "post"
tags = ["blog"]

[cascade.extra]
banner = "default-banner.png"
+++

Every page under the section now renders with the post template, carries the blog tag, and exposes page.extra.banner — unless it sets those fields itself. extra and taxonomies merge per key: the page's own keys win, cascaded keys fill the gaps.

Cascadable keys: template, draft, render, toc, insert_anchor_links, in_sitemap, in_search_index, tags, taxonomies, authors, extra. URL-affecting keys (slug, path, aliases) cannot cascade and are ignored with a warning.

On multilingual sites, a cascade only applies within its own language tree — _index.ko.md cascades to .ko pages, _index.md to default-language pages.

Sort direction

Each sort_by value has a different natural direction, chosen to match what authors usually want:

reverse flips whichever direction is natural for the chosen sort_by. For example, a blog index sorted by date is newest-first by default; setting reverse = true switches it to oldest-first.

+++
title = "Blog"
sort_by = "date"
# reverse = false (default) → newest first
# reverse = true            → oldest first
+++

Examples

Blog with Pagination

+++
title = "Blog"
sort_by = "date"
paginate = 10
paginate_path = "p"
+++

Generates: /blog/, /blog/p/2/, /blog/p/3/

With the default paginate_path = "page", the URLs are /blog/page/2/, /blog/page/3/, … — page 1 always stays at the section URL.

Documentation

+++
title = "Docs"
page_template = "doc-page"
sort_by = "weight"
+++

All pages use doc-page.html template and sort by weight.

Section with Feed

+++
title = "News"
generate_feeds = true
+++

Generates /news/rss.xml.

Full Front Matter Reference

All available fields in one block. Copy and remove what you don't need.

+++
title = "Section Title"
description = "Section description"
template = "section"
page_template = "custom-page"
sort_by = "date"
reverse = false
paginate = 10
paginate_path = "page"
transparent = false
generate_feeds = true
redirect_to = ""
draft = false
weight = 0
+++

Nested Sections

Sections can contain other sections:

content/
└── docs/
    ├── _index.md           # /docs/
    ├── getting-started/
    │   ├── _index.md       # /docs/getting-started/
    │   └── install.md      # /docs/getting-started/install/
    └── guides/
        ├── _index.md       # /docs/guides/
        └── deploy.md       # /docs/guides/deploy/

Access subsections in templates:

{% for sub in section.subsections %}
<a href="{{ sub.url }}">{{ sub.title }}</a>
<small>({{ sub.pages_count }})</small>
{% endfor %}

Template Variables

When rendering a section page (_index.md), these variables are available:

Use page.url for the current section URL.

section.list / section_list

<ul class="auto-list">
  {{ section.list | safe }}
</ul>

For building a custom pagination UI with paginator, see Data Model › Paginator.

Transparent Sections

Use transparent = true to merge pages into parent section:

+++
title = "2024 Posts"
transparent = true
+++

Pages appear in the parent's section.pages list.

Asset Colocation

Just like regular pages, sections can have colocated assets. Place non-markdown files in the same directory as the _index.md file.

Example Structure:

content/
└── gallery/
    ├── _index.md       <-- The section index
    ├── banner.jpg      <-- Section asset
    └── icon.png        <-- Section asset

These assets are copied to the output directory relative to the section.

Accessing Assets in Templates

You can access the list of section assets in your templates using section.assets. This returns an array of relative paths to the files (from the content directory).

<!-- In section.html -->
<div class="gallery">
  {% for asset in section.assets %}
    <img src="{{ get_url(path=asset) }}" alt="Section Asset">
  {% endfor %}
</div>

Section vs Page

Use _index.md when you need to list child pages.

See Also

• Pages — Individual content files and front matter
• Taxonomies — Classify content by tags and categories
• Data Model — Section properties in templates