---
title: "Getting started"
description: "Install Andromeda and render your first Markdown page."
url: "https://www.andromedacms.dev/docs/getting-started"
updated_at: 2026-09-24
---

# 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`:

```ruby
gem "andromeda_cms"
```

Then install it and run the generator:

```bash
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

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

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

```ruby
# 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`:

```markdown
---
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.