feat: add sub-section support for pages

config/default.php

@@ -87,6 +87,9 @@
         //    ]
         //],
         'frontmatter' => 'yaml', // front matter format: `yaml`, `ini`, `toml` or `json`
+        'sections' => [ // sections options
+            //'nested' => true, // enable sub-sections (subfolders with index.md)
+        ],
         'body' => [
             'toc' => ['h2', 'h3'], // headers used to build the table of contents
             'highlight' => false, // enables code syntax highlighting

docs/2-Content.md

@@ -1,7 +1,7 @@
 <!--
 description: "Create content and organize it."
 date: 2021-05-07
-updated: 2026-02-04
+updated: 2026-02-25
 -->
 # Content
 
@@ -30,19 +30,26 @@ Project files organization.
 ```plaintext
 <mywebsite>
 ├─ pages
-|  ├─ blog            <- Section
-|  |  ├─ post-1.md    <- Page in Section
-|  |  └─ post-2.md
+|  ├─ blog               # Section
+|  |  ├─ index.md        # Section's index (optional)
+|  |  ├─ post-1.md       # Page in Section
+|  |  ├─ post-2.md
+|  |  └─ tutorials       # Sub-section
+|  |     ├─ index.md     # Sub-section's index (required)
+|  |     ├─ tuto-1.md    # Page in Sub-section
+|  |     └─ advanced     # Nested Sub-section
+|  |        ├─ index.md
+|  |        └─ tuto-2.md
 |  ├─ projects
 |  |  └─ project-a.md
-|  └─ about.md        <- Root page
+|  └─ about.md           # Root page
 ├─ assets
-|  ├─ styles.scss     <- Asset file
+|  ├─ styles.scss        # Asset file
 |  └─ logo.png
 ├─ static
-|  └─ file.pdf        <- Static file
+|  └─ file.pdf           # Static file
 └─ data
-   └─ authors.yml     <- Data collection
+   └─ authors.yml        # Data collection
 ```
 
 ### Built website tree
@@ -52,11 +59,17 @@ Result of the build.
 ```plaintext
 <mywebsite>
 └─ _site
-   ├─ index.html               <- Generated home page
+   ├─ index.html                   # Generated home page
    ├─ blog/
-   |  ├─ index.html            <- Generated list of posts
-   |  ├─ post-1/index.html     <- A blog post
-   |  └─ post-2/index.html
+   |  ├─ index.html                # Generated list of posts
+   |  ├─ post-1/index.html         # A blog post
+   |  ├─ post-2/index.html
+   |  └─ tutorials/
+   |     ├─ index.html             # Sub-section list
+   |     ├─ tuto-1/index.html
+   |     └─ advanced/
+   |        ├─ index.html          # Nested sub-section list
+   |        └─ tuto-2/index.html
    ├─ projects/
    |  ├─ index.html
    |  └─ project-a/index.html
@@ -559,7 +572,7 @@ It must be the first thing in the file and must be a valid [YAML](https://en.wik
 | `title`     | Title             | File name without extension.                       | `Post 1`      |
 | `layout`    | Template          | See [_Lookup rules_](3-Templates.md#lookup-rules). | `404`         |
 | `date`      | Creation date     | File creation date (PHP _DateTime_ object).        | `2019/04/15`  |
-| `section`   | Section           | Page's _Section_.                                  | `blog`        |
+| `section`   | Section           | Page's _Section_ (or _Sub-section_).               | `blog`        |
 | `path`      | Path              | Page's _path_.                                     | `blog/post-1` |
 | `slug`      | Slug              | Page's _slug_.                                     | `post-1`      |
 | `published` | Published or not  | `true`.                                            | `false`       |
@@ -749,7 +762,7 @@ In « 1_The first project.md »:
 
 ### Section
 
-Some dedicated variables can be used in a custom _Section_ (i.e.: `<section>/index.md`).
+Some dedicated variables can be used in a custom _Section_ (i.e.: `<section>/index.md`) or _Sub-section_ (i.e.: `<section>/<sub-section>/index.md`).
 
 #### sortby
 
@@ -824,6 +837,41 @@ circular: true
 ---
 ```
 
+### Sub-sections
+
+A _Sub-section_ is created when a subfolder inside a _Section_ (or another _Sub-section_) contains an `index.md` file. This enables a hierarchical tree of sections.
+
+:::important
+The `index.md` file is **required** to turn a subfolder into a _Sub-section_. Without it, the subfolder's pages belong to the nearest parent section.
+:::
+
+#### Structure example
+
+```plaintext
+pages/
+└─ blog/
+   ├─ index.md           <- "blog" Section
+   ├─ post-1.md
+   └─ tutorials/
+      ├─ index.md        <- "blog/tutorials" Sub-section
+      ├─ tutorial-1.md
+      └─ advanced/
+         ├─ index.md     <- "blog/tutorials/advanced" Sub-section
+         └─ tutorial-2.md
+```
+
+In this example:
+
+- `blog` is the root _Section_, containing `post-1`.
+- `blog/tutorials` is a _Sub-section_ of `blog`, containing `tutorial-1`.
+- `blog/tutorials/advanced` is a _Sub-section_ of `blog/tutorials`, containing `tutorial-2`.
+
+Each sub-section has its own pages collection and supports the same variables as a section (`sortby`, `pagination`, `cascade`, `circular`).
+
+#### Accessing sub-sections in templates
+
+See the [Sub-sections template variables](3-Templates.md#sub-sections) for details on how to use sub-sections in Twig templates.
+
 ### Home page
 
 Like another section, _Home page_ support `sortby` and `pagination` configuration.

docs/3-Templates.md

@@ -196,6 +196,19 @@ All rules are detailed below, for each page type, in the priority order.
 6. `list.<format>.twig`
 7. `_default/list.<format>.twig`
 
+#### Sub-section lookup
+
+For a sub-section (e.g. `blog/tutorials`), the layout lookup also includes the parent section layouts:
+
+1. `<section>/<subsection>/index.<format>.twig`
+2. `<section>/<subsection>/list.<format>.twig`
+3. `section/<section>/<subsection>.<format>.twig`
+4. `<section>/list.<format>.twig` _(parent section)_
+5. `section/<section>.<format>.twig` _(parent section)_
+6. `_default/section.<format>.twig`
+7. `list.<format>.twig`
+8. `_default/list.<format>.twig`
+
 ### Type _vocabulary_
 
 1. `taxonomy/<plural>.<format>.twig`
@@ -355,6 +368,8 @@ The `page` variable contains built-in variables of a page **and** those set in t
 | `page.filepath`       | File system path.                                      | `Blog/Post 1.md`           |
 | `page.type`           | `homepage`, `page`, `section`, `vocabulary` or `term`. | `page`                     |
 | `page.pages`          | Collection of all sub pages.                           | _Collection_               |
+| `page.subsections`    | Collection of child sub-sections (sections only).      | _Collection_               |
+| `page.parent`         | Parent section (sub-sections only).                    | _Page_                     |
 | `page.translations`   | Collection of translated pages.                        | _Collection_               |
 
 :::important
@@ -822,6 +837,104 @@ The `dump` function dumps information about a template variable. This is mostly
 The [_debug mode_](4-Configuration.md#debug) must be enabled.
 :::
 
+### Sub-sections
+
+The following functions and [tests](#tests) help work with [sub-sections](2-Content.md#sub-sections). Sub-sections must be [enabled in the configuration](4-Configuration.md#pages-sections).
+
+#### subsections
+
+Returns the collection of child sub-sections of a _section_ page.
+
+```twig
+{{ subsections(page) }}
+```
+
+_Example:_
+
+```twig
+{% if page is has_subsections %}
+  {% for sub in subsections(page) %}
+    <a href="{{ url(sub) }}">{{ sub.title }}</a>
+  {% endfor %}
+{% endif %}
+```
+
+#### parent_section
+
+Returns the parent section of a sub-section page (or `null` if the page is a root section).
+
+```twig
+{{ parent_section(page) }}
+```
+
+_Example:_
+
+```twig
+{% if page is subsection %}
+  <a href="{{ url(parent_section(page)) }}">Back to {{ parent_section(page).title }}</a>
+{% endif %}
+```
+
+#### section_breadcrumb
+
+Returns an array of pages from the root section down to the given section, useful for building breadcrumb navigation.
+
+```twig
+{{ section_breadcrumb(page) }}
+```
+
+_Example:_
+
+```twig
+{% for crumb in section_breadcrumb(page) %}
+  <a href="{{ url(crumb) }}">{{ crumb.title }}</a>
+  {% if not loop.last %} / {% endif %}
+{% endfor %}
+```
+
+#### all_pages_recursive
+
+Returns all pages of a section including pages from its sub-sections, recursively.
+
+```twig
+{{ all_pages_recursive(page) }}
+```
+
+_Example:_
+
+```twig
+{% for p in all_pages_recursive(page) %}
+  <a href="{{ url(p) }}">{{ p.title }}</a>
+{% endfor %}
+```
+
+#### section_tree
+
+Returns the full hierarchical tree of all sections as an array of nodes. Each node contains a `page` entry (the section page) and a `children` array of sub-nodes.
+
+```twig
+{{ section_tree() }}
+```
+
+_Example:_
+
+```twig
+{% macro render_tree(tree) %}
+  <ul>
+  {% for node in tree %}
+    <li>
+      <a href="{{ url(node.page) }}">{{ node.page.title }}</a>
+      {% if node.children is not empty %}
+        {{ _self.render_tree(node.children) }}
+      {% endif %}
+    </li>
+  {% endfor %}
+  </ul>
+{% endmacro %}
+
+{{ _self.render_tree(section_tree()) }}
+```
+
 ### d
 
 The `d()` function is the HTML version of [`dump()`](#dump) and use the [Symfony VarDumper Component](https://symfony.com/doc/5.4/components/var_dumper.html) behind the scenes.
@@ -837,6 +950,30 @@ The `d()` function is the HTML version of [`dump()`](#dump) and use the [Symfony
 The [_debug mode_](4-Configuration.md#debug) must be enabled.
 :::
 
+## Tests
+
+> [Tests](https://twig.symfony.com/doc/tests/index.html) can be used with the `is` operator to check if a variable meets certain criteria.
+
+### subsection
+
+Tests if a _section_ page is a sub-section (i.e. has a parent section).
+
+```twig
+{% if page is subsection %}
+  This section is a sub-section.
+{% endif %}
+```
+
+### has_subsections
+
+Tests if a _section_ page has child sub-sections.
+
+```twig
+{% if page is has_subsections %}
+  This section contains sub-sections.
+{% endif %}
+```
+
 ## Sorts
 
 Sorting collections (of pages, menus or taxonomies).

docs/4-Configuration.md

@@ -1,7 +1,7 @@
 <!--
 description: "Configure your website."
 date: 2021-05-07
-updated: 2025-12-09
+updated: 2026-02-25
 -->
 # Configuration
 
@@ -477,6 +477,22 @@ pages:
   pagination: false
 ```
 
+### pages.sections
+
+Options for [_Sections_](2-Content.md#section).
+
+#### Enable sub-sections
+
+Sub-sections (nested sections created by subfolders containing an `index.md` file) are disabled by default. Enable them with the `nested` option:
+
+```yaml
+pages:
+  sections:
+    nested: true
+```
+
+See the [Content documentation](2-Content.md#sub-sections) for details on how to structure sub-sections and the [Templates documentation](3-Templates.md#sub-sections) for available functions and tests.
+
 ### pages.paths
 
 Apply a custom [`path`](2-Content.md#predefined-variables) for all pages of a **_Section_**.

phpunit.xml.dist

@@ -27,6 +27,9 @@
     <testsuite name="IntegrationCliTests">
       <file>./tests/IntegrationCliTests.php</file>
     </testsuite>
+    <testsuite name="SubSectionTests">
+      <file>./tests/SubSectionTests.php</file>
+    </testsuite>
   </testsuites>
   <coverage includeUncoveredFiles="false"></coverage>
 </phpunit>