What This Example Demonstrates
This example shows how allow-external-paths enables reading content from outside the site directory, which can replace traditional plugin systems.
🌍 External Relative Paths
Path: ../shared/
Content from outside site directory using relative paths with allow-external-paths option.
📝 Local Content
Path: local-content/
Standard local includes for comparison.
⚙️ External Configuration
Build mode: production
Features: external-paths,symlinks
TOML data from external sources that CI/CD could manage.
🔧 External Build Info (with Fallback)
Build: local-dev
Commit: development
External source with fallback to local defaults - perfect for CI/CD workflows.
Plugin System Alternative
Instead of implementing a plugin system, external paths allow:
- Drop-in content: Build systems can place files in external directories
- Shared resources: Multiple sites can reference the same content directory
- Dynamic configuration: CI/CD pipelines can provide TOML data files
- Version control flexibility: External content can live in separate repos
Security Model
External paths require dual-flag security:
- Config flag:
options = ["allow-external-paths"]in the step - CLI flag:
--allow-external-pathswhen running SSI
Both must be present. This prevents accidental external path access.
Deployment Command
ssi --allow-external-paths deploy site/ output/Content Sources
Use Cases
- Shared documentation components maintained by separate team
- Build-time injection of feature flags or environment data
- Multi-site setups with common technical content
- Development vs production content switching
- CI/CD systems providing configuration at build time