Page Files

Page files are TOML files with a .page suffix. They tie together data files and templates, and also function as placeholders for the output file in the file hierarchy.

All variables are optional. The following affect the operation of SSG:

template

Specifies the template to use, relative to the templates directory, e.g. if the template you want to use for the page is:

/home/user/mysite/templates/blog/important.jinja

you should put

template = "blog/important.jinja"

in your .page file.

If no template is specified, no file will be created, but the data associated with the page will still be available to other pages. For example, a page such as global.page could be created in the root of the content directory and the data defined therein would be accessible to all the templates as pages["global"].data.

suffix

Each .page file in the content hierarchy that specifies a template has a matching file in the public directory that is the result of applying the specified context to the specified template. This file usually has the same name as the .page file, except the suffix is changed to .html. The suffix variable allows you to specify a different replacement suffix. For example if you wanted the .page file to be replaced with an xml file, you should put

suffix = ".xml"

in your page file.

weight

An integer. SSG makes an ordered list of siblings (page files in the same directory) and adjacent siblings available to the template. These siblings are ordered by weight, then filename. If you wanted to give the processed page a weight of 10, you should put:

weight = 10

in your .page file.

You can also put:

weight = "None"

This excludes the page from the sibling list. Note that "None" is a string; TOML does not have a null type.

By default, pages have a weight of 0, apart from any page with the filename index.page, which has a default weight of "None".

The weight is available to the templates as page.weight. It will be None if set to "None" by the TOML.

tags

A list of strings that are interpreted as tags, e.g.

tags = ['tag1', 'tag2', 'tag3']

The tags for all pages are made available to the templates in the variable tags, which is a mapping of tag string to a list of page identifiers that have specified that tag.

[data]

Everything in the [data] section is made available to the templates as a dictionary. For example:

[data]
images = ["img_1.webp", "img_2.webp", "img_3.webp"]

would make page.data.images available as an array, allowing you to do things like:

{% for img in page.data.images %}
<img src="{{img}}"/>
{% endfor %}

[content]

Each entry in the [content] section links an identifier to the processed contents of a file, specified as a path relative to the directory containing the .page, file. Thus if you had a page file at:

/home/user/mysite/content/blog/2025-08-10.page

and a TOML file containing data at:

/home/user/mysite/content/blog/data/2025-08-10.toml

you could put

[content]
mydata = "data/2025-08-10.toml"

and that data would be available to your templates as a dictionary named page.content.mydata.

See Content Files for details of how different types of file are processed and made available to the templates.