Skip to main content

Quick-start guide

Perron is a gem that generates static sites from your Rails app.

Requirements

  • Ruby 3.4+
  • Rails 7.0+

Quickstart

Run

rails new my-new-site --minimal -T -O -m https://perron.railsdesigner.com/library/new/template.rb

Manual installation

Start by adding Perron to your Rails app:

bundle add perron

bin/rails perron:install

This creates a configuration file at config/initializers/perron.rb:

Perron.configure do |config|
  config.site_name = "Chirp Form"

  # config.site_description = "Description for meta tags"
  # config.default_url_options = {host: "chirpform.com", protocol: "https"}
end

Create your first content

Perron organizes content into collections. Each collection needs:

  • a resource class in app/models/content/
  • a controller in app/controllers/content/
  • views in app/views/content/
  • content files in app/content/{collection_name}/

Use the built-in generator to create one:

bin/rails generate content Post

This creates:

  • app/content/posts/; content files go here
  • app/models/content/post.rb; resource class
  • app/controllers/content/posts_controller.rb
  • app/views/content/posts/

And adds a route: resources :posts, module: :content, only: %w[index show]

Add content

Create your first article in app/content/posts/hello-world.md:

---
title: Hello World
description: My first Perron post
---

# Hello World

This is my first post built with Perron!

Then run the Rails server to see your site:

bin/dev

Visit http://localhost:3000/posts/hello-world to see your content.

Build for production

Generate static files for deployment:

RAILS_ENV=production bin/rails perron:build

This creates HTML files in the /output/ directory, ready to deploy to any static hosting platform.

Browse the Library for deployment templates to platforms like Netlify, S3 and statichost.eu.