SiteCompiler — The Lightweight Static Site Generator for DevelopersSiteCompiler is a modern, minimal static site generator (SSG) designed for developers who value speed, simplicity, and control. It strikes a balance between powerful features and an unopinionated, extendable architecture so you can build blogs, documentation sites, marketing pages, and component-driven frontends without unnecessary complexity.
Why choose a lightweight SSG?
Heavyweight tools can add cognitive overhead: long build times, steep configuration, and tightly coupled ecosystems. A lightweight SSG focuses on the essentials:
- Fast build times for iterative development.
- Simple configuration so you spend time writing content, not tweaking build files.
- Extensibility through plugins and a minimal API surface.
- Predictable output that’s easy to deploy to any static hosting provider.
SiteCompiler aims to deliver those benefits while remaining friendly to modern developer workflows.
Core principles of SiteCompiler
- Minimalism: Only the features developers actually need are included by default.
- Convention over configuration: Sensible defaults let you get started with zero setup.
- Composability: Small, focused plugins extend functionality without bloating the core.
- Performance-first: Fast local dev server, incremental builds, and optimized production output.
- Developer ergonomics: Clear error messages, good defaults, and tight CLI UX.
Key features
-
Fast CLI and dev server
- Instantaneous startup and live reload.
- File-watching with granular rebuilds to keep iteration rapid.
-
Simple content model
- Support for Markdown with frontmatter (YAML/TOML/JSON).
- Optionally use MDX-style JSX in content for interactive components.
-
Flexible templating
- Use whichever templating approach you prefer: lightweight template files, single-file components, or render functions.
- Built-in partials and layout support.
-
Extensible plugin system
- Plugins can add data sources, transform content, register routes, or inject build-time logic.
- A small plugin API surface keeps authoring plugins straightforward.
-
Asset pipeline
- Image optimization, CSS minification, and JS bundling only when needed.
- Outputs immutable, cache-friendly filenames for production.
-
Data-driven pages
- Generate pages from JSON/CSV/Markdown or external APIs.
- Simple pagination and collection helpers.
-
Ready for modern deploy targets
- Outputs static files that work with any host (Netlify, Vercel, GitHub Pages, S3, etc.).
- Optionally produce adapter outputs for edge/CDN-friendly deployments.
Typical developer workflow
- scaffold with zero config
- Run a single command to create a project with sensible defaults and folder structure (content/, layouts/, public/).
- write content
- Create Markdown files with frontmatter to define routes, metadata, and custom fields.
- develop locally
- Start the dev server, see live updates when editing, and use fast refresh for components.
- extend with plugins
- Add image processing, search indexing, or a custom data source via plugins.
- build and deploy
- Run a production build that outputs optimized, cache-friendly files ready to upload.
Example project structure
A minimal SiteCompiler site often looks like:
content/ blog/ 2025-09-01-launch.md layouts/ default.html components/ Nav.jsx public/ robots.txt siteconfig.yml Frontmatter in a blog post:
--- title: "Launch Day" date: 2025-09-01 tags: ["release", "product"] --- Plugin ecosystem and extensibility
SiteCompiler’s plugin model encourages small, single-purpose packages. Example plugins:
- sitecompiler-plugin-images — automatic responsive image generation and srcset support.
- sitecompiler-plugin-sitemap — generate XML sitemaps using your routes and priorities.
- sitecompiler-plugin-search — build a lightweight client-side search index at build time.
A plugin can:
- register new route generators,
- add transforms for content files,
- hook into build steps (before/after),
- expose configuration options.
This keeps the core tiny while allowing teams to opt into functionality as needed.
Performance considerations
Performance is a core design goal:
- Incremental builds: only changed files and dependent pages are rebuilt.
- Parallelism: CPU-bound tasks (image processing, bundling) run in parallel where possible.
- Cache friendly outputs: hashed filenames, gzip/Brotli-ready assets, and minimal runtime.
For large sites, SiteCompiler supports sharding and pagination strategies to keep memory usage bounded.
SEO, accessibility, and best practices
SiteCompiler encourages best practices by default:
- Manage metadata via frontmatter and layout templates.
- Generate canonical URLs and sitemap automatically (when plugin enabled).
- Ensure semantic HTML and accessible components in examples and starter templates.
- Support for structured data (JSON-LD) injection in templates.
Use cases and who it’s for
- Solo developers and small teams building blogs, docs, and marketing sites.
- Design systems teams creating component-driven static sites.
- Engineers who want predictable, framework-agnostic output and control over build steps.
- Projects that need fast CI builds and easy deployment to edge/CDN hosts.
Comparisons (quick)
| Concern | SiteCompiler | Heavier SSGs |
|---|---|---|
| Startup/config | Minimal, zero-config friendly | Often heavy config |
| Build speed | Fast, incremental | Slower on large sites |
| Extensibility | Plugin-first, small API | Larger ecosystems, steeper learning |
| Opinionation | Unopinionated | May lock you into conventions/frameworks |
Getting started (quick commands)
- scaffold: sitecompiler init
- dev server: sitecompiler dev
- build: sitecompiler build
- serve locally: sitecompiler serve
Example: generating blog pages from Markdown
- Place posts in content/blog/.
- Add frontmatter with title/date.
- Create a layout at layouts/blog.html that iterates over posts.
- Build — SiteCompiler will generate /blog/* pages and an index.
Community and contribution
A lightweight project thrives on community plugins and starter templates. Contributing small plugins, layouts, and guides helps the ecosystem grow while keeping the core focused.
SiteCompiler’s appeal is straightforward: get developers from idea to deployed static site quickly, without wrestling configuration or long build cycles. It’s designed to be a practical, extendable tool for real-world developer workflows.
Leave a Reply