> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby SDK

> The ButterCMS Ruby SDK provides a production-ready idiomatic Ruby interface with Rails support and a resilient fallback data store.

## Installation

<Tabs>
  <Tab title="Bundler (Gemfile)">
    Add to your Gemfile:

    ```ruby theme={null}
    gem 'buttercms-ruby'
    ```

    Then run:

    ```bash theme={null}
    bundle install
    ```
  </Tab>

  <Tab title="gem install">
    ```bash theme={null}
    gem install buttercms-ruby
    ```
  </Tab>
</Tabs>

## Initialization

Configure the SDK with your Read API token from the [ButterCMS Settings](https://buttercms.com/settings/).

```ruby theme={null}
require 'buttercms-ruby'

ButterCMS::api_token = "your_api_token"
```

## Configuration options

```ruby theme={null}
# Enable test/preview mode for draft content
ButterCMS::test_mode = true

# Customize timeout settings (in seconds)
ButterCMS::read_timeout = 5.0   # Default: 5.0
ButterCMS::open_timeout = 2.0   # Default: 2.0
```

| Option         | Type    | Default | Description                              |
| -------------- | ------- | ------- | ---------------------------------------- |
| `api_token`    | String  | -       | Your ButterCMS Read API token (required) |
| `test_mode`    | Boolean | `false` | Enable preview mode for draft content    |
| `read_timeout` | Float   | `5.0`   | Read timeout in seconds                  |
| `open_timeout` | Float   | `2.0`   | Connection open timeout in seconds       |

## API methods

### Pages

Retrieve and search pages created in the ButterCMS dashboard.

```ruby theme={null}
# List all pages of a type
pages = ButterCMS::Page.list("landing_page", {
  page: 1,
  page_size: 10,
  locale: "en",
  preview: 1,    # Include draft content
  levels: 2      # Depth of nested references
})

# Access page data
pages.each do |page|
  puts page.fields[:headline]
end

# Retrieve a single page
page = ButterCMS::Page.get("landing_page", "home-page", {
  locale: "en"
})
puts page.fields[:headline]
puts page.fields[:body]

# Search pages
results = ButterCMS::Page.search("search query", {
  page: 1,
  page_size: 10
})
```

### Collections

Fetch content from Collections (structured data tables).

```ruby theme={null}
# List collection items with pagination metadata
params = { page: 1, page_size: 10, locale: "en" }
collection = ButterCMS::Content.list("faq", params)

collection.items.each do |item|
  puts item[:question]
  puts item[:answer]
end

# Fetch multiple collections at once (without pagination)
content = ButterCMS::Content.fetch(["faq", "navigation"], {
  locale: "en"
})
```

### Blog Posts

Access the built-in Blog Engine for posts, categories, tags, and authors.

```ruby theme={null}
# List blog posts
posts = ButterCMS::Post.all({
  page: 1,
  page_size: 10
})

posts.each do |post|
  puts post.title
end

# Access pagination metadata
puts posts.meta.next_page
puts posts.meta.previous_page

# Retrieve a single post
post = ButterCMS::Post.find("my-post-slug")
puts post.title
puts post.body

# Search posts
results = ButterCMS::Post.search("search query", {
  page: 1,
  page_size: 10
})
```

### Authors

```ruby theme={null}
# List all authors
authors = ButterCMS::Author.all

# Retrieve a single author
author = ButterCMS::Author.find("jennifer-smith")
puts author.first_name
puts author.last_name
```

### Categories

```ruby theme={null}
# List all categories
categories = ButterCMS::Category.all

# Retrieve a single category
category = ButterCMS::Category.find("news")
puts category.name
puts category.slug
```

### Tags

```ruby theme={null}
# List all tags
tags = ButterCMS::Tag.all

# Each tag has name and slug
tags.each do |tag|
  puts tag.name
end
```

### Feeds

Retrieve RSS, Atom, and Sitemap feeds.

```ruby theme={null}
# Get RSS feed
rss = ButterCMS::Feed.find(:rss)
puts rss.data

# Get Atom feed
atom = ButterCMS::Feed.find(:atom)

# Get Sitemap
sitemap = ButterCMS::Feed.find(:sitemap)
```

## Query parameters reference

| Parameter       | Applies To                | Description                           |
| --------------- | ------------------------- | ------------------------------------- |
| `page`          | Posts, Pages              | Page number for pagination            |
| `page_size`     | Posts, Pages              | Number of items per page              |
| `exclude_body`  | Posts                     | Exclude post body for faster response |
| `author_slug`   | Posts                     | Filter posts by author                |
| `category_slug` | Posts                     | Filter posts by category              |
| `tag_slug`      | Posts                     | Filter posts by tag                   |
| `include`       | Authors, Categories, Tags | Include `recent_posts` with response  |
| `locale`        | Pages, Collections        | Locale code for localized content     |
| `preview`       | Pages                     | Set to `1` to include draft content   |
| `levels`        | Pages                     | Depth of nested references (1–3)      |

## Complete example

```ruby theme={null}
require 'buttercms-ruby'

ButterCMS::api_token = ENV["BUTTERCMS_API_TOKEN"]

def fetch_homepage_data
  # Fetch the home page
  page = ButterCMS::Page.get("landing_page", "home", {
    locale: "en"
  })

  # Fetch navigation from collection
  navigation = ButterCMS::Content.fetch(["main_navigation"])

  # Fetch recent blog posts
  posts = ButterCMS::Post.all({
    page: 1,
    page_size: 3
  })

  {
    page: page,
    navigation: navigation["main_navigation"],
    recent_posts: posts
  }
rescue => e
  puts "Error fetching content: #{e.message}"
  nil
end

# Usage
data = fetch_homepage_data
if data
  puts "Page headline: #{data[:page].fields[:headline]}"
  puts "Navigation items: #{data[:navigation].length}"
  puts "Recent posts: #{data[:recent_posts].length}"
end
```

## Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/ButterCMS/buttercms-ruby">
    View source code, report issues, and contribute
  </Card>

  <Card title="RubyGems" icon="gem" href="https://rubygems.org/gems/buttercms-ruby">
    Package details and version history
  </Card>
</CardGroup>