Examples

Example Sites

Super-Simple Includes comes with example sites numbered 1–25 and 99. Each example builds on the previous ones, introducing new concepts progressively from absolute basics to production-ready patterns.

Example Overview

All examples are in the examples/ directory of the repository.

Learning Path

Core concepts (examples 1–5)

1. Start with example 1 — the absolute minimum config
2. Example 2 — add your first template processing
3. Example 3 — convert Markdown content to HTML
4. Example 4 — verify assets with checksums
5. Example 5 — handle mixed content types automatically

Include patterns (examples 6–10)

6. Example 6 — build reusable HTML components
7. Example 7 — manage variables in TOML
8. Example 8 — step ordering: pipeline sequencing rules and leftovers-okay
9. Example 9 — control inline vs. block formatting
10. Example 10 — per-page content resolution (SSI’s most flexible feature)

Multi-page generation (example 11)

11. Example 11 — generate many pages from one template

Template rendering (example 12)

12. Example 12 — expand one token into many rendered items using TOML or directory sources

System integration (examples 13–16)

13. Example 13 — alias emoji with the also field; reuse one template across different data sources
14. Example 14 — use datetime, git, environment, and metadata sources; live data on every build
15. Example 15 — navigation and index sources: prev/next links, position tokens, per-page metadata, and auto-generated listings
16. Example 16 — process CSS and JS as templates; use type = "raw" for verbatim content
17. Example 17 — file handling and preserve patterns

Practical sites (examples 18–21)

18. Example 18 — a complete blog with navigation, excerpts, and template-rendered index
19. Example 19 — conditional section via fallback gate: show or hide a whole HTML block at build time
20. Example 20 — JavaScript infinite scroll built entirely from SSI navigation data
21. Example 21 — external content access as a plugin system alternative

Advanced composition (examples 22–25)

22. Example 22 — advanced context and nested destination organization
23. Example 23 — counter source for repeated blocks with distinct data; comparison with template rendering
24. Example 24 — token construction and two-pass resolution
25. Example 25 — nested processing: independent configuration, include sources, and emoji namespace per section

Full-site (example 99)

99. Example 99 — all features together in a production-ready site

Example Structure

Each example contains:

• site/ — The source files and ssi-config.toml
• expected-deploy/ — The built output
• expected-deploy-hashes.toml — Hash record of expected output files
• test-assertions.toml — Semantic assertions run by the test suite
• README.md — Explanation of what the example teaches

Using the Examples

Run locally

# Clone the repository
                git clone https://codeberg.org/mattdm/super-simple-includes.git
                cd super-simple-includes
                
                # Build an example
                cd examples/01-copy-only
                ssi deploy site/ output/
                

Copy as a starting point

# Copy an example as your starting point
                cp -r examples/10-page-specific/site/ my-new-site/
                cd my-new-site/
                # Edit files, then:
                ssi deploy . ../my-deploy/
                

Run the test suite

All examples are validated by the integration test suite on every commit:

python3 scripts/run-all-tests.py integration