Lukasz Czapiewski - Full Stack Developer

The static-site-builder gem is a Ruby-powered static site generator that compiles ERB templates into static HTML. It's perfect when you want Rails-like templating without the overhead of a full Rails application. This guide will walk you through everything you need to know to build and deploy static sites with this gem.

Installation and Setup

Install the gem:

gem install static-site-builder

Or clone from GitHub:

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

Generate a new site:

# If installed as gem
static-site-builder new my-site

# Or if using from repo
ruby bin/generate my-site

You'll be prompted to choose your stack using an interactive menu with arrow key navigation. Select your preferred:

Template Engine: ERB or Phlex
JavaScript Bundler: Importmap, ESBuild, Webpack, Vite, or none
CSS Framework: TailwindCSS, shadcn/ui, or plain CSS
JavaScript Framework: Stimulus, React, Vue, Alpine.js, or vanilla JS

Once generated, install dependencies:

cd my-site
bundle install
npm install  # Required for importmap projects and JS frameworks

Project Structure

The generator creates a complete project structure with all necessary files:

my-site/
├── Gemfile              # Dependencies (static-site-builder, sitemap_generator, etc.)
├── package.json         # JS dependencies (if needed)
├── Rakefile            # Build tasks (includes sitemap generation)
├── config/
│   ├── importmap.rb    # Importmap config (if using importmap)
│   └── sitemap.rb      # Sitemap generation config
├── app/
│   ├── views/
│   │   ├── layouts/    # ERB layout templates
│   │   ├── pages/      # Page templates
│   │   └── components/ # Reusable components/partials
│   ├── javascript/
│   │   ├── application.js  # Main JavaScript entry point
│   │   └── controllers/    # Stimulus controllers (if using Stimulus)
│   └── assets/
│       └── stylesheets/     # CSS source files
└── lib/
    ├── site_builder.rb   # Compiles your site (auto-generated)
    └── page_helpers.rb   # Page metadata (auto-generated)

The lib/site_builder.rb file is automatically generated and configured based on your stack choices. It handles ERB/Phlex compilation and scans app/views/pages/ for templates, compiling them to HTML in the dist/ directory.

Creating Pages

Pages are ERB templates in app/views/pages/. The file structure determines the URL structure:

index.html.erb → /
about.html.erb → /about
blog/post.html.erb → /blog/post

Example page:

<% @title = 'About Me' %>
<% @description = 'Learn more about me' %>

<div class="container mx-auto px-4 py-8">
  <h1><%= @title %></h1>
  <p>Your content here</p>
</div>

Layouts and Partials

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

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title><%= @title || 'My Site' %></title>
  <link rel="stylesheet" href="/assets/stylesheets/application.css">
</head>
<body>
  <%= render 'shared/header' %>
  <%= page_content %>
  <%= render 'shared/footer' %>
  
  <% if importmap_json %>
    <script type="importmap">
      <%= raw importmap_json %>
    </script>
  <% end %>
  
  <script type="module">import "application";</script>
</body>
</html>

Use render for partials and nested layouts. The page_content method yields the page content.

JavaScript with Stimulus

Configure JavaScript modules in config/importmap.rb:

pin 'application', preload: true
pin '@hotwired/stimulus', to: 'stimulus.min.js', preload: true
pin_all_from 'app/javascript/controllers', under: 'controllers'

Create Stimulus controllers in app/javascript/controllers/:

import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
  connect() {
    console.log('Controller connected')
  }
}

In your pages, specify which JavaScript modules to load:

<% @js_modules = ['application', 'my-controller'] %>

Styling with Tailwind CSS

If you selected TailwindCSS during generation, the gem automatically creates tailwind.config.js and package.json with the necessary build scripts. Your source CSS goes in app/assets/stylesheets/application.css, and the Rake tasks handle building CSS automatically.

The generated package.json includes scripts like:

{
  "scripts": {
    "build:css": "tailwindcss -i ./app/assets/stylesheets/application.css -o ./dist/assets/stylesheets/application.css --minify",
    "watch:css": "tailwindcss -i ./app/assets/stylesheets/application.css -o ./dist/assets/stylesheets/application.css --watch"
  }
}

Building Your Site

The generator creates a Rakefile with all necessary build tasks. Use these commands:

rake build:all - Build HTML and CSS
rake build:html - Build HTML only
rake build:css - Build CSS only
rake build:production - Clean build for production

The build process compiles your templates to static HTML in the dist/ directory, ready for deployment.

Development Workflow

For development with live reload, use:

rake dev:server

This starts a local server, watches for file changes, and automatically rebuilds. The gem includes WebSocket support for live reloading in the browser.

Page Metadata and Helpers

The generator creates lib/page_helpers.rb automatically. This file contains page metadata that's used for SEO and sitemap generation:

module PageHelpers
  PAGES = {
    '/' => {
      title: 'My Page',
      description: 'A great page',
      url: 'https://example.com',
      image: 'https://example.com/image.jpg',
      priority: 1.0,
      changefreq: 'weekly'
    }
  }.freeze
end

The builder automatically loads metadata from PageHelpers::PAGES and sets @title, @description, @url, and @image instance variables for use in your templates. Simply add new pages to the PAGES hash.

Sitemap Generation

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. Update it to set your domain:

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

The sitemap is generated from your PageHelpers::PAGES metadata during rake build:all. It will be output to dist/sitemaps/sitemap.xml.gz.

Deployment

Once built, your static site is in the dist/ directory. Deploy it to any static hosting service:

Netlify - Connect your Git repository and set build command to rake build:production
Vercel - Similar setup with build command
GitHub Pages - Use GitHub Actions to build and deploy
Cloudflare Pages - Connect repo and configure build settings
Any CDN - Upload the dist/ directory contents

Best Practices

Keep it simple - Use partials for reusable components
Organise by feature - Group related pages in subdirectories
Use helpers - Centralise page metadata and common logic
Version control - Commit your source files, ignore dist/
Test locally - Always preview before deploying

Next Steps

You're now ready to build static sites with the static-site-builder gem. Check out the GitHub repository for more examples and documentation. Happy building!