Reference

The pages section can be used to show any combination of subpages for the current page or any other page in your site.

Example

title: Blog

sections:

  drafts:
    headline: Drafts
    type: pages
    status: draft
    templates: article

  published:
    headline: Published Articles
    type: pages
    status: listed
    templates: article

The pages section has multiple options to control what kind of pages should be displayed, how they should be displayed and what happens if a new page is added.

Section properties

Property	Type	Required	Default	Description
create	mixed			Optional array of templates that should only be allowed to add.
empty	mixed			Sets the text for the empty state box
headline	mixed			The headline for the section. This can be a simple string or a template with additional info from the parent page.
help	mixed			Sets the help text
image	mixed			Image options to control the source and look of page previews
info	string			Optional info text setup. Info text is shown on the right (lists) or below (cards) the page title.
layout	string		list	Section layout. Available layout methods: `list`, `cards`.
limit	int		20	Sets the number of items per page. If there are more items the pagination navigation will be shown at the bottom of the section.
max	int			Sets the maximum number of allowed entries in the section
min	int			Sets the minimum number of required entries in the section
page	int			Sets the default page for the pagination. This will overwrite default pagination.
parent	string			Sets the query to a parent to find items for the list
size	string		auto	The size option controls the size of cards. By default cards are auto-sized and the cards grid will always fill the full width. With a size you can disable auto-sizing. Available sizes: `tiny`, `small`, `medium`, `large`, `huge`
sortBy	string			Overwrites manual sorting and sorts by the given field and sorting direction (i.e. `date desc`)
sortable	bool		true	Enables/disables manual sorting
status	string			Filters pages by their status. Available status settings: `draft`, `unlisted`, `listed`, `published`, `all`.
templates	mixed			Filters the list by templates and sets template options when adding new pages to the section.
text	string		{{ page.title }}	Setup for the main text in the list or cards. By default this will display the page title.

Headline

The headline will be displayed above the pages section. You can pass a simple headline as a string or you can provide translations for multiple languages, if you have an international editing team.

Single language

headline: Articles

Multiple languages

headline:
  en: Articles
  de: Artikel
  es: Artículos

Placeholders

You can inject information from the current page into the headline with template placeholders using our query language.

headline: "Articles for {{ page.title }}"

Layout

The pages can either be displayed as a simple list or as cards with preview images. The list view is the default view.

List layout (default)

The list layout is perfect for more text-heavy pages, like articles, link lists, simple pages, etc.

layout: list

Cards layout

The card layout is great for media-heavy pages, like galleries, products, projects, etc.

layout: cards

Page information

You can fine-tune the display text and additional information for every page in the list with the text and info options.

text

By default the page title is shown in the list for every page. You can use our template syntax with query language to fetch any information from the page and display that instead of the title.

text: " {{ page.title.upper }}"

info

If you want to display additional information for each page, like a date, year, category or any other field value, you can use the template syntax with query language in the info option.

info: " {{ page.date.toDate('Y-m-d') }}"

Preview images

The (preview) image for each item in the list is configured with the image option:

image: page.image.findBy("name", "cover")

The default preview image is the first image in the folder.

If you need more fine-grained control you can setup the image for each page with further options.

Show icon instead of image

To display the icon set in the page blueprint or a default icon instead of a preview image, you can set the imageoption to false:

image: false

query

An image query, default page.image

image:
  query: page.children.first.image

cover

Whether or not the image will cover the available space.
Options: true, false (default)

image:
  cover: true

Examples

ratio

A freely selectable image ratio

image:
  ratio: 16/9

Examples

back

Set an image background.
Options: pattern (default), black, white

image:
  query: page.image.findBy("name", "cover")
  cover: true
  ratio: 1/1
  back: black

Examples

Empty state

With the empty option you can define the message which is displayed when no pages are listed in the section.

empty: No articles yet

Filtering pages

Parent

By default, the current page is being used as the parent to find children for the list. With this option, any page on your site can be the parent of the section

parent: site.find("blog")

Status

You can filter the list of pages by their status. The available status values are

status: draft

Note that an "Add" button for new pages will only be available if you use either status: draft or status: all.

Templates

You can define a list of templates that will be available when adding new pages to the section. It will also be used to filter pages to be contained in the list.

Single template

template: article

Multiple templates

templates:
  - project
  - article

"Add" button

Editors can add new pages to the section with the "Add" button in the top right corner.

Why?

New pages are always added as draft. If the "Add" button showed up in sections that only show listed or unlisted pages, the "Add" button would lead to a confusing interaction for editors, as the new page would not show up in the section.

Sorting

sortBy

You can sort the list of pages by a given field in descending or ascending order.

sortBy: date desc

sortable

You can switch off manual sorting entirely with the sortable option.

sortable: false

Limits

limit

The limit property sets how many pages will be shown per page. If there are more entries in the section, the pagination navigation will be shown at the bottom of the section.

limit: 20

max

You can define a maximum number of pages, that will be allowed in this section. After the maximum is reached, the add button will be hidden and no more pages can be added.

max: 10

min

You can also define the minimum number of pages, that need to be added in order to make the page valid.

min: 2