File Sources

Processing steps (`[[step]]`)

File sources define directories or TOML files containing content to be processed. They are processed in the order they appear in the configuration. Emoji identifiers must be unique across all processing steps.

[[step]]
                emoji = "📄"
                path = "pages/"
                processing = "page"

Required Fields

emoji - Unique emoji identifier that acts as a globally unique ID for this source. Used for logging and debugging. Must be different from all other processing steps and include sources. Suggestions: 📄 (pages), 🎨 (assets), 📁 (files), 🖼️ (images), 📱 (mobile), 🔤 (fonts)
path - Directory path (relative to source directory or absolute) - must be unique across all processing steps. Directory sources should end with / for clarity
processing - Processing type: "page", "copy", "preserve", "include", or "nested"

Optional Fields

options - Array of strings for configuration flags
- "allow-external-paths" - Allow reading from paths outside the source directory, including symlinks and relative/absolute paths like ../docs/ (requires --allow-external-paths CLI flag)
- "leftovers-okay" - Allow leftover tokens without error on pages from this source (for page processing only)
- "checksum" - Verify file integrity using xxHash3 checksums (for copy processing only)
- "skip-by-checksum" - Skip copying files that already match expected checksum (implies checksum verification)
destination - Subdirectory within deploy directory for this processing step’s output

Processing Types

page - Process HTML files for include tokens; replace emoji tokens with resolved include content
copy - Copy files recursively by default; follows symlinks and copies their target content (use options = ["flat"] for top-level only)
preserve - Copy specified files from previous deployment to new deployment
include - Define a data source providing content for include tokens (requires type field; no output files produced directly)
nested - Run a separate ssi-config.toml as part of this deploy; all nested output goes to the same deploy directory

Note: Conflicting output files from different sources produce warnings, or errors when using --strict mode.

Destination Field

The optional destination field allows you to deploy files into subdirectories within the deploy directory:

[[step]]
                emoji = "🎨"
                path = "assets/"
                processing = "copy"
                # Files deployed to deploy_dir/assets/
                
                [[step]]
                emoji = "🔤"
                path = "fonts/"
                destination = "assets/fonts"
                processing = "copy"
                # Files deployed to deploy_dir/assets/fonts/

Destination Rules

Security: Destination paths are validated against .. and absolute paths
No Magic Parents: Parent directories must be created by previous processing steps
Ordering: File sources must be processed in order so parents exist before children
Flat Processing: Each processing step processes only top-level files. Subdirectories are noted during validation

Example: Nested Destinations

# First: Create parent directory
                [[step]]
                emoji = "🎨"
                path = "assets/"
                destination = "assets"
                processing = "copy"
                
                # Then: Create nested subdirectories
                [[step]]
                emoji = "🖌️"
                path = "css/"
                destination = "assets/css"
                processing = "copy"
                
                [[step]]
                emoji = "⚡"
                path = "js/"
                destination = "assets/js"
                processing = "copy"

Example: Overlapping Source Directories

Due to flat processing, subdirectories in source paths are ignored, allowing this pattern:

# This source ignores assets/css/ subdirectory (flat processing)
                [[step]]
                emoji = "🎨"
                path = "assets/"
                destination = "assets"
                processing = "copy"
                
                # This source specifically handles the css files
                [[step]]
                emoji = "🖌️"
                path = "assets/css/"
                destination = "assets/css"
                processing = "copy"

The assets/ source will copy top-level files, ignoring the assets/css/ subdirectory. The assets/css/ subdirectory is explicitly handled by a later source. This allows fine-grained control over different file types within the same directory structure.

Note on Validation: The ssi validate command will note subdirectories in sources to help you ensure your configuration is complete. During ssi deploy, output is cleaner without these notes.