Configuration Reference

SSI uses ssi-config.toml in the site’s root directory to define the processing pipeline.

Configuration Format

Everything is a [[step]]. Steps are executed in order.

[[step]]
                emoji      = "📄"        # required: unique emoji token prefix
                path       = "pages/"    # required: directory or file path
                processing = "page"      # required: what to do with these files

Processing Types

`processing`	What it does
`"page"`	Process HTML files: replace emoji tokens with resolved include content
`"copy"`	Copy files to the deploy directory (recursive by default; use `options = ["flat"]` for top-level only)
`"preserve"`	Copy files from the previous deployment (for atomic deploys)
`"include"`	Define a content source; use `type` to specify the format
`"nested"`	Run a nested `ssi-config.toml` as part of this pipeline; each nested config has its own emoji namespace
`"copylist"`	Copy a specific list of files to the deploy directory; list file is specified with the `copylist` key

Include Sources

Include sources make content available for token replacement in pages. They all use processing = "include" with a type field:

[[step]]
                emoji      = "📝"
                path       = "content/"
                processing = "include"
                type       = "markdown"     # "plain", "markdown", or "html"

`type`	Use for
`"plain"`	Text files; HTML-escaped by default
`"markdown"`	Markdown files; rendered to HTML
`"html"`	HTML fragment files; included as-is
`"datetime"`	Built-in: date/time tokens
`"git"`	Built-in: git repository info
`"environment"`	Built-in: selected environment variables
`"counter"`	Built-in: numeric counter with increment/peek

Common Configuration Examples

Basic website

[[step]]
                emoji = "📄"
                path = "pages/"
                processing = "page"
                
                [[step]]
                emoji = "🎨"
                path = "assets/"
                processing = "copy"
                
                [[step]]
                emoji = "📝"
                path = "content/"
                processing = "include"
                type = "markdown"
                options = ["adjust-headers"]

With TOML data and datetime

[[step]]
                emoji = "📄"
                path = "pages/"
                processing = "page"
                
                [[step]]
                emoji = "🕐"
                processing = "include"
                type = "datetime"
                timezone = "UTC"
                options = ["inline"]
                
                [[step]]
                emoji = "💬"
                path = "strings.toml"
                processing = "include"
                type = "plain"
                options = ["inline"]
                
                [[step]]
                emoji = "📝"
                path = "content/"
                processing = "include"
                type = "markdown"

Common Options

Option	Applies to	Description
`"inline"`	include	Collapse newlines to spaces (for inline substitution)
`"adjust-headers"`	include with `type = "markdown"`	Shift markdown headers down one level
`"no-escape"`	include with `type = "plain"`	Include without HTML escaping (for CSS/JS)
`"flat"`	copy	Copy only top-level files; subdirectories trigger warnings
`"leftovers-okay"`	any	Allow unresolved tokens without error
`"allow-external-paths"`	any	Allow paths outside the site directory

Optional Fields

Field	Applies to	Description
`destination`	page, copy	Subdirectory within deploy directory
`type`	include	Content format (see above)
`fallback`	include	Alternative source if primary is missing
`context`	include	Override per-page directory resolution

Path Resolution

Relative paths start from the source directory
Directories should end with / for clarity
Absolute paths require options = ["allow-external-paths"] and the --allow-external-paths CLI flag

Note for users of --allow-external-paths: as of v0.240.x, the flag no longer bypasses is_protected_directory checks for nested .toml-form paths and copylist paths. Configs that used --allow-external-paths with absolute paths pointing to system directories (e.g., /etc, /usr) will now be rejected at config validation time. This is intentional — --allow-external-paths permits reading from outside the site directory, but never from protected system paths regardless of the flag.

Configuration Reference