Templates

Templates are placed in the templates directory. They are referenced in the .page files as filepaths relative to this directory.

Available variables

The following variables may be referenced in the templates:

page

The page variable exposes the following attributes:

id

The page's identifier. This is the normalized filepath of the .page file relative to the content directory, less the .page suffix.

path

The full filepath of the output file, relative to the public directory. If no template was specified in the .page file, and hence no output file was created, path will be None.

filename

The filename of the output file. If no file was created, None. This is particularly useful when working with files in the same directory.

dir

The directory, relative to the content directory, containing the .page file. If there is an output file, this will also be the directory relative to the public directory containing the output file.

subdirs

Any non-ignored sub-directories in dir.

tags

The list of strings categorizing the page, as defined by the tags variable in the .page file.

content

The content created by processing the files specified in the [content] table of the .page file. The data from each processed file is bound to the defined identifier. For example:

[content]
json = "mydata.json"

binds the data structure created by passing the contents of mydata.json to Python's json.loads() to the variable page.content.json in the template. The data structure is dependent on the type of file bound — TOML files and sharded text files are mappings, unsharded text files are strings, and JSON files can be pretty much anything.

data

A mapping of identifiers to TOML data, as defined under the [data] table in the .page file. For example:

[data]
images = ["img-1.webp", "img-2.webp", "img-3.webp"]

would make the array of image filenames available to the templates as page.data.images.

siblings

A list of the page identifiers of other page files residing in the same directory. The page identifier of any page file with a weight of None will be excluded from the list. These are ordered by weight, then by filepath.

lighter

The page identifier of the page in the siblings list that would appear before the current page..

heavier

The page identifier of the page in the siblings list that would appear after the current page.

pages

A mapping of page identifiers to pages for all the page files processed by SSG. Given a page identifier, you can access any of the attributes documented above for the page variable. For example, you could get the tags specified for index.page in the root of the content hierarchy with pages['index'].tags.

The data from pages that have no corresponding output file, created by not specifying a template in the .page file, are also available through pages. For example, you could create globals.page in the content directory, and access the data specified in it through pages['globals'].data.

tags

A mapping of tag strings, as defined by any .page files using the tags statement, to a list of page identifiers containing those tags. The list is sorted by weight, then filepath.

root

A string such as ../../ which may be pre-pended to a filepath relative to the content directory (and hence also the public directory) to make that filepath relative to the page. For example if you had a file named style.css in a css directory in the content directory, you could refer to it from your page as

root ~ 'css/style.css'

This empowers you to make all links relative to the page, allowing you to deploy websites to any domain, and at any depth within a domain.

It even allows you to, in many cases, view your website directly on your local file system, without the need for a web server.

Custom filters

The following custom filters are added to Jinja's environment and can be used in the templates:

latest

This filter is used to allow versioned immutable files to simplify cache management. If you had css/styles.3.css and css/styles.4.css in your content directory and you called a template with

{{ root ~ "css/styles.css" | latest }}

from blog/example.page it would output ../css/styles.4.css.

This allows you to keep older versions of style files etc. around for however long you expect cached versions of your html pages to be accessing them.

dimensions

This filter is used to access the width and height of images, so that they can be correctly inserted in <img> tags, thus avoiding layout shift. If you had an the image images/example.webp in your content directory, you could use:

{% set url = root ~ "images/example.webp" %}
{% set dims = url | dimensions %}
<img src="{{url}} height={{dims.height}} width={{dims.width}}/>

markdown

This filter allows you to convert text content written in commonmark to html. For example if you loaded a markdown file with:

[content]
main = example.md

You could insert the html derived from this markdown into your template with

{{ page.content.main | markdown }}