Content files

Overview

The [content] table in the .page file links identifiers with filepaths relative to the directory containing the .page file. SSG processes these files and binds the results to the identifiers to make them available to the template. For example, if you had the page file blog/test.page containing:

  [content]
  main = "html/test.html"

then content of the file blog/html/test.html would be processed and the result made available to the templates as page.content.main.

The types of file that can be processed are detailed below.

TOML

TOML files are identified by a suffix of .toml and are processed by Python's standard tomllib module. This turns the data into a mapping linking TOML identifiers to various types of data, including strings, numbers, arrays and nested dictionaries. It is very flexible. For more details, see the official TOML website.

For example, if you had a TOML file named example.toml containing

myarray = [1, 2, 3]

and you had the following in your .page file

[content]
example = "example.toml"

then {{page.content.example.myarray}} would give you access to the array in your template.

JSON

JSON files are identified by the suffix .json and are processed by Python's standard json module. JSON is a lot more flexible than TOML with the type of top level data structure it creates. If you had a JSON file named example.json containing

[1, 2, 3]

and you had the following in your .page file

[content]
example = "example.json"

then {{page.content.example}} would give you access to the array in your template.

Sharded text files

Any file having a suffix other than .toml or .json is treated as a generic text file; this includes html and markdown files. It is possible to section up these files by using "shard markers".

A shard marker has the form

<!-- shard: identifier -->

where identifier is any valid TOML identifier. Dotted identifiers are allowed, and identifiers need not be unique. A shard marker must be alone on its own line. Processing as a sharded file is triggered by the presence of a shard marker on the first line of the file.

These sharded files are converted to TOML and then processed by Python's standard tomllib module. If the identifier is unique, the shard text is wrapped in a multiline string and bound to it. The shard texts of non-unique identifiers are each wrapped in a multiline string and gathered into an array, ordered in the same sequence as the shards in the file. For example if example.html contained

<!-- shard a.b -->
<p>foo</p>
<!-- shard c -->
<p>other thing</p>
<!-- shard a.b -->
<p>bar</p>

and your .page file contained

[content]
main = "example.html"

then page.content.main would give you access to the mapping created by processing the following TOML:

a.b = ["""<p>foo</p>""", """<p>bar</p>"""]
c = """<p>other thing</p>"""

White space is preserved by TOML's multi-line string format, so sections of markdown will work as expected.

Unsharded text files

If a file does not have either of the extensions .toml or .json and also does not have a shard marker on the first line of the file, its contents are simply bound to the identifier as a multi-line string.