Processing Types

Processing Types

File sources support several processing types that determine how files are handled:

Copy Processing

Copy files recursively by default (use options = ["flat"] for top-level only; deploy to destination if provided).

• Copies entire directory trees preserving structure (default)
• Add "flat" processing option to copy only top-level files
• By default, follows symlinks and copies their target content as regular files; use options = ["preserve-symlinks"] to keep symlinks as-is, or options = ["adjust-symlinks"] to adjust relative symlink paths for the deploy location
• Best for static assets like images, CSS, JavaScript files, and third-party libraries

[[step]]
                emoji = "🎨"
                path = "assets/"
                processing = "copy"
                # Copies all files and subdirectories recursively
                
                [[step]]
                emoji = "📦"
                path = "vendor/"
                processing = "copy"
                options = ["flat"]  # Only copy top-level files
                

Page Processing

Process HTML template files for include tokens (processing = "page").

• Scans each HTML file for emoji tokens and replaces them with resolved include content
• Subdirectories in the source path are noted during validation
• Best for HTML templates that need dynamic content inclusion

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

Preserve Processing

Copy specified files from previous deployment to new deployment directory. This is useful for preserving dynamically generated files across atomic deployments.

[[step]]
                emoji = "💾"
                path = "preservelist.txt"
                processing = "preserve"
                

preservelist.txt Format

The preserve list supports multiple pattern types for flexible file preservation:

• One pattern per line
• Lines starting with # are comments
• Empty lines are ignored
• Security Rules (violations cause build failure):
  • Paths cannot start with / (no absolute paths)
  • Paths cannot contain ../, ..\\, ./, .\\, /../, or \\..\\ (no path traversal)
  • These are ERRORS, not warnings - the build will fail if violated

Pattern Types

Example preservelist.txt

# Fixed files
                sitemap.xml
                robots.txt
                
                # Entire directories (recursive)
                logs/
                uploads/
                
                # Directory-scoped globs (non-recursive)
                products/*.html
                exports/*.csv
                
                # Directory wildcards (non-recursive)
                pagefind/*
                
                # Extension globs (recursive)
                *.db
                

Copylist Processing

Copy specific files from the source directory to the deployment directory using a list file (same format as preserve). Unlike copy processing, which copies entire directories, copylist gives precise control over which individual files are deployed.

[[step]]
                emoji = "📋"
                processing = "copylist"
                copylist = "copylist.txt"          # required: path to the list file
                path = "assets/"                   # optional: scope source root to subdirectory
                destination = "static/"            # optional: prefix in deploy directory
                options = ["missing-ok"]           # standard file-processing options apply
                

The copylist parameter is required and identifies the list file. The path parameter is optional — when set, it scopes the source root to that subdirectory (so entries in the list file are relative to it). When omitted, entries are relative to the site source directory root.

copylist.txt Format

The format is identical to preservelist.txt. See the Preserve Processing section above for pattern documentation.

Example copylist.txt

# Specific files to deploy alongside pages
                assets/logo.png
                assets/fonts/MyFont.woff
                shared/styles.css
                

Nested Processing

Run a separate ssi-config.toml as part of the current deploy. The nested config is processed in full, and its output goes into the same deploy directory as the main site. The entire deploy remains a single atomic operation.

Directory path form — path points to a directory:

[[step]]
                emoji = "📰"
                path = "blog/"
                processing = "nested"
                

SSI looks for blog/ssi-config.toml as the config and uses blog/ as the nested source root.

Explicit config path form — path ends with .toml:

[[step]]
                emoji = "📰"
                path = "blog-config.toml"
                processing = "nested"
                

SSI uses blog-config.toml as the config. The nested source root is the parent config’s source directory.

Each nested config has its own emoji namespace — the same emoji can be used in both the main config and a nested config without collision.

Constraints:

• A nested config cannot itself contain a processing = "nested" step (no double-nesting)
• Any failure inside a nested config fails the entire deploy

Notes

• Recursive copying: Copy processing now copies entire directory trees by default (since version 0.201.x). For top-level files only, use options = ["flat"]
• File conflicts: Conflicting output files from different sources produce warnings, or errors when using --strict mode
• All processing types respect the destination field for organizing output structure