Getting started

Andromeda brings Astro’s content collections to an ordinary Ruby on Rails app. Markdown and MDX files in app/content/ are validated against a schema, converted once at deploy time, and rendered by your own controllers and views.

Requirements

• Ruby 3.2 or newer
• Rails 8.0 or newer

No database is required for content, and no Node.js toolchain: the gem ships a precompiled parser for common platforms.

Install

Add the gem to your Gemfile:

gem "andromeda_cms"

Then install it and run the generator:

bundle install
bin/rails generate andromeda:install

bundle add andromeda_cms does the same in one step, if you prefer.

The installer creates app/content/, an initializer, and adds the build directory to .gitignore and .dockerignore.

Your first collection

bin/rails generate andromeda:collection posts title:string pub_date:date

That writes four things: an entry class, a controller, views, and a route.

# app/models/content/post.rb
module Content
  class Post < Andromeda::Entry
    collection :posts, base: "app/content/posts", pattern: "**/*.{md,mdx}"

    attribute :title, :string
    attribute :pub_date, :date

    # scope :published, -> { where(draft: false) }
  end
end

Add required: true to an attribute to make a file without it fail the build instead of rendering with a blank.

Write a file at app/content/posts/hello-world.md:

---
title: Hello world
pub_date: 2026-09-01
---

## It works

The body is ordinary GFM Markdown.

Start the server and visit /posts/hello-world. The page is rendered by your own view, so the layout, the header and anything else in your application behave exactly as they always do.

What happens when

	Development	Production
Parsing and rendering	On demand, when a file changed	Once, during andromeda:build
A request	Converts if stale, then reads	Reads the converted result
Watcher process	None	None

andromeda:build is hooked into assets:precompile, so a standard Rails deploy already runs it.