Include Sources

Include Sources (`[[step]]` with `processing = "include"`)

Include sources define content loaded into templates via emoji-based tokens.

[[step]]
                emoji = "📎"
                path = "blocks/"
                processing = "include"
                type = "html"

Required Fields

emoji — unique emoji prefix for include tokens; must differ from all other steps
path — directory or TOML file path; directories should end with /
processing — must be "include" for include sources
type — content type: "auto" (default), "html", "markdown", "plain", or "raw"

Optional Fields

Field	Type	Description
`options`	array	flags — see below
`context`	string	override automatic page-context resolution
`fallback`	string	alternative source path if primary missing

Options

Option	Applies to	Description
`inline`	all	convert newlines to spaces for inline token replacement
`allow-external-paths`	all	allow paths outside the site directory (requires `--allow-external-paths` CLI flag)
`leftovers-okay`	all	allow unresolved tokens from this source without error
`no-escape`	plain	include content as-is without HTML escaping
`adjust-headers`	markdown	shift all headers down one level (h1→h2, h2→h3, etc.)
`markdown-h2`–`markdown-h6`	markdown	shift markdown headers to start at the specified level

Content Types

auto — detect content type by file extension: .html → HTML, .md → Markdown, .txt → plain (HTML-escaped), other → plain; allows mixing content types in one directory
plain — HTML-escaped by default; use no-escape for CSS, JS, or JSON content
markdown — renders CommonMark to HTML
html — included as-is
raw — zero processing: no HTML escaping, no newline handling, always inline; for pre-minified or verbatim content

File Extension Requirements

Directory sources must use the matching extension for the content type:

plain — .txt
markdown — .md
html — .html

Files with mismatched or missing extensions produce warnings. Under --strict, these warnings become errors.

Context Field

By default, SSI uses the page name to resolve per-page content: about.html looks in content/about/. The context field overrides this.

# Always use "product" subdirectory regardless of page name
                [[step]]
                emoji = "📦"
                path = "content/"
                processing = "include"
                type = "html"
                context = "product"
                
                # Always use the root directory
                [[step]]
                emoji = "🌐"
                path = "content/"
                processing = "include"
                type = "html"
                context = "_"

context must be a valid directory basename (no / or \) or the special value "_" for root.

Example

# HTML fragments (header, footer, nav)
                [[step]]
                emoji = "📎"
                path = "blocks/"
                processing = "include"
                type = "html"
                
                # Inline text variables from TOML
                [[step]]
                emoji = "💬"
                path = "strings.toml"
                processing = "include"
                type = "plain"
                options = ["inline"]
                
                # Markdown content with header adjustment
                [[step]]
                emoji = "📝"
                path = "articles/"
                processing = "include"
                type = "markdown"
                options = ["markdown-h2"]

See ssi help markdown-header-alignment for header alignment details, and ssi help source-fallback for the fallback field.