Static Site Builder

⚠️ Active Development: This project is currently in active development.

A Ruby-based generator and builder for creating static HTML sites with working JavaScript. No backend required - just compile your ERB files to static HTML and deploy anywhere.

📖 Learn more: Demo | Project Overview | Getting Started Guide

Why This Exists

Generates standalone static sites from ERB templates, with a working dev server, file watching, and live reload. Generated projects are self-contained: the build code lives in the generated repo (lib/site_builder.rb).

Why Choose This Over Other Approaches

Better SEO & Search Rankings: Unlike Single Page Applications (SPAs) that rely on client-side JS rendering, static HTML is immediately crawlable by search engines. Your content is fully indexed from the first request, leading to better search rankings and significantly faster page loads.

Simplicity Over Complexity: No need for complex JavaScript frameworks, hydration, or server-side rendering setups. Create .html.erb files that compile to clean, static HTML. Add JavaScript only where you need interactivity, not as a requirement for rendering.

Developer Experience: Work with familiar Rails patterns (layouts, pages, partials) without a full Rails application, allowing you to host it for free directly on Cloudflare CDNs and other static hosting services.

Version Control & Mobile Editing: Your entire site is code in a Git repository. Track changes, collaborate, and edit from anywhere - even your phone with tools like Cursor Agents. No database migrations or CMS interfaces needed. Lightning fast.

Main Objective

Generate static HTML pages using ERB files. Simple and flexible - add your own JavaScript bundling and CSS processing as needed.

Installation

gem install static-site-builder
# or
git clone https://github.com/Ancez/static-site-builder
cd static-site-builder
bundle install

Quick Start

Option 1: Install as a gem

gem install static-site-builder
static-site-builder new my-site

Option 2: Use directly from repo

git clone https://github.com/Ancez/static-site-builder
cd static-site-builder
bundle install
ruby bin/generate my-site

Generated sites use:

ERB templates for HTML generation
local build code in lib/site_builder.rb (no runtime dependency on this gem)

What Gets Generated

A clean project structure that depends on gems:

my-site/
├── Gemfile              # Dependencies (rake, webrick, sitemap_generator, etc.)
├── Rakefile            # Build tasks (assets, HTML, CSS, sitemap, dev server)
├── config/
│   └── sitemap.rb      # Sitemap generation config
├── app/
│   ├── views/
│   │   ├── layouts/
│   │   ├── pages/
│   ├── javascript/
│   └── assets/
│       └── stylesheets/
└── lib/
    └── site_builder.rb   # Compiles your site

How It Works

Generator (static-site-builder new ...) - Creates the project structure
Generated build code (lib/site_builder.rb) - Compiles pages/layouts and provides WebSocket live reload
Build tools (Rakefile) - Defines build:* tasks and dev:server
Your tools - Add Tailwind, bundlers, etc, and wire them via package.json scripts

Features

🎯 Static HTML output - No server-side rendering needed
🔧 Simple & flexible - ERB files, add your own tools
📦 Self-contained generated sites - No runtime dependency on this gem
🚀 Fast builds - Compile once, deploy everywhere
🔄 Live reload - Rebuild and refresh on changes in development

Templates

Generated sites use ActionView for Rails-like templates, helpers, layouts, and partials.

Create a layout in app/views/layouts/application.html.erb:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="/assets/stylesheets/application.css">
</head>
<body>
  <main>
    <%= yield %>
  </main>

  <% if content_for?(:javascript) %>
    <%= yield(:javascript) %>
  <% end %>
</body>
</html>

yield outputs the page content. Use content_for(:javascript) to push scripts into the layout.

Partials

Partials work like Rails, including locals::

<%= render partial: 'shared/header', locals: { title: 'Home' } %>

Adding JavaScript

Include JavaScript files in your pages:

<% content_for(:javascript) do %>
  <script src="/assets/javascripts/application.js"></script>
<% end %>

If you add a package.json with a scripts.build, rake build:assets will run npm run build. If you do not, it copies app/javascript/ into dist/assets/javascripts/.

Set up your own bundler if needed and output to dist/assets/javascripts/. See setup guides:

ESBuild
Webpack - see webpack documentation
Vite - see vite-plugin-ruby

Adding CSS

Write CSS in app/assets/stylesheets/application.css. Use any CSS tool you prefer:

Tailwind CSS
PostCSS, Sass, Less, or any other CSS processor - just compile your CSS files to dist/assets/stylesheets/ before building HTML.

Generating Sitemaps

Sitemap generation is automatically configured when you generate a new site. The sitemap_generator gem is included in the Gemfile, and config/sitemap.rb is automatically created.

The sitemap is automatically generated from all pages in app/views/pages/ during rake build:all. Update config/sitemap.rb to set your domain:

SitemapGenerator::Sitemap.default_host = 'https://yourdomain.com'

You can customize priority, changefreq, and lastmod in config/sitemap.rb. The sitemap will be generated in dist/sitemaps/sitemap.xml.gz during the build process.

Examples

Basic ERB Site

static-site-builder new my-site

Notable Projects

Sites built with Static Site Builder:

lukaszczapiewski.com - Personal portfolio and blog

Your website? Built with Static Site Builder? Submit a PR to add it here!

Requirements

Ruby 3.0+
Bundler

Optional (if you want to use Tailwind CSS or JavaScript bundlers):

Node.js and npm

Development

Running Your Site Locally

After generating a site, you can run it locally with auto-rebuild and live reload:

cd my-site
bundle install

# Start development server (auto-rebuilds on file changes)
rake dev:server

This will:

Build your site to dist/
Start a web server at http://localhost:3000
Watch for file changes and rebuild automatically
Auto-refresh your browser when files change

You can change the port with:

PORT=8080 rake dev:server

Building for Production

# Build everything (assets + HTML)
rake build:all

# Or just HTML
rake build:html

# Output is in dist/ directory

Deployment

The dist/ directory contains your complete static site and can be deployed to any static hosting provider.

See deployment guides for specific platforms:

Generator Development

# Clone the repo
git clone https://github.com/Ancez/static-site-builder
cd static-site-builder

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Build the gem
gem build static-site-builder.gemspec

Testing

The project includes comprehensive test coverage:

Unit tests for Generator and Builder classes
Integration tests for full build workflows
End-to-end tests for complete workflows
Tests for all stack combinations

Run tests with:

bundle exec rspec

View coverage report:

open coverage/index.html

Architecture

This generator follows the Rails pattern:

Generator gem - Creates project structure
Builder gem - Handles compilation (separate gem: static-site-builder)
Standard gems - Reuse existing Ruby gems
Generated code - Minimal, uses gem dependencies

Contributing

Contributions welcome! Especially:

Documentation improvements
New features and improvements

License

MIT