Pages and sections

A page is a file made up of a front matter and a body.

Front matter

The front matter is a collection of variables (in key/value format) surrounded by ---.

Example:

---
title: "The title"
date: 2019-02-21
tags: [tag 1, tag 2]
customvar: "Value of customvar"
---

Body

Body is the main content of a page, it could be written in Markdown or in plain text.

Example:

# Header

[toc]

## Sub-Header 1

Lorem ipsum dolor [sit amet](https://example.com), consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<!-- excerpt -->
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Sub-Header 2

![Description](/image.jpg "Title")

## Sub-Header 3

:::tip
This is advice.
:::

File prefix

The filename can contain a prefix to define date or weight variables of the page (used by sortby).

date

The date prefix is used to set the date of the page, and must be a valid date format (i.e.: « YYYY-MM-DD »).

Example:

In « 2019-04-23_My blog post.md »:

the prefix is « 2019-04-23 »
the date of the page is « 2019-04-23 »
the title of the page is « My blog post »

weight

The weight prefix is used to set the sort order of the page, and must be a valid integer value.

Example:

In « 1_The first project.md »:

the prefix is « 1 »
the weight of the page is « 1 »
the title of the page is « The first project »

Section

Some dedicated variables can be used in a custom Section (i.e.: <section>/index.md).

sortby

The order of pages in a Section can be changed.

Available values are:

date: more recent first
title: alphabetic order
weight: lightest first

Example:

---
sortby: title
---

More options:

---
sortby:
  variable: date    # "date", "updated", "title" or "weight"
  desc_title: false # used with "date" or "updated" variable value to sort by desc title order if items have the same date
  reverse: false    # reversed if true
---

pagination

The global pagination configuration is used by default, but you can change it for a specific Section.

Example:

---
pagination:
  max: 5
  path: "page"
---

Pagination can be disabled for a Section:

---
pagination: false
---

cascade

Any variables in cascade are added to the front matter of all sub pages.

Example:

---
cascade:
  banner: image.jpg
---

circular

Set circular to true to enable circular navigation with page.<prev/next>.

Example:

---
circular: true
---

Sub-section

A nested folder that explicitly contains an index.md file is turned into a sub-section of its parent Section.

<mywebsite>
└─ pages
   └─ blog                 <- Section
      ├─ index.md
      ├─ post-1.md         <- Page in Section "blog"
      └─ 2024              <- Sub-section (contains an "index.md")
         ├─ index.md
         └─ post-2.md      <- Page in Section "blog" *and* sub-section "blog/2024"

A sub-section:

is a Section (same type, variables and layout resolution) available at its own URL (e.g.: /blog/2024/)
is rendered with the layouts of its parent Sections if it doesn't have its own (e.g.: blog/list.html.twig)
can be nested at any depth (e.g.: blog/2024/06/)
lists its own pages, and its pages also belong to each of their parent Sections
is not listed in its parent Section