Ruby Logo

Ruby blog engine

ButterCMS is an API-based Ruby blog engine that integrates with Ruby apps in minutes. Use ButterCMS with Rails, Sinatra, and other Ruby frameworks to build CMS-powered apps quickly. ButterCMS works great for blogs, dynamic pages, and more.

Table of Contents


Learn how to quickly build a custom blog with great SEO. This guide uses the Sinatra web framework but Butter integrates with any Ruby web app (we also have a Rails guide). Full working example code is available on Github.

If you need help after reading this, contact us via email, livechat, or book a time with to pair with one of our developers.

Display posts

To display posts we create a simple /blog route in our app and fetch blog posts from the Butter API. See our API reference for additional options such as filtering by category or author. The response also includes some metadata we'll use for pagination.

require 'rubygems'
require 'bundler'
require 'buttercms-ruby'

ButterCMS::api_token = ''

class App < Sinatra::Base
  get '/blog' do
    params[:page] ||= 1

    @posts = ButterCMS::Post.all(:page => params[:page], :page_size => 10)
    @next_page = @posts.meta.next_page
    @prev_page = @posts.meta.previous_page

    erb :index

Next we'll create a simple view named blog.html.erb that displays our posts and pagination links:


<!-- List of posts -->
<% @posts.each do |post| %>
  <a href="<%= url("/blog/#{post.slug}") %>"><%= post.title %></a>
<% end %>

<!-- Pagination links -->
  <% if @previous_page %>
  <a href="<%= url("/blog?page=#{@prev_page}") %>">Prev</a>
  <% end %>

  <% if @next_page %>
  <a href="<%= url("/blog?page=#{@next_page}") %>">Next</a>
  <% end %>

We'll also create an additional route for displaying individual posts:

class App < Sinatra::Base


  get '/blog/:slug' do
    @post = ButterCMS::Post.find(params[:slug])

    erb :post

The view for displaying a full post includes information such as author, publish date, and categories. See a full list of available post properties in our API reference. We use the content_for Sinatra helper for setting the HTML title and meta description in the <head> tag of the page.

<% content_for(:title) { @post.seo_title } %>
<% content_for(:meta_description) { @post.meta_description } %>

<!-- Post title -->
<h2><%= @post.title %></h2>

<!-- Post author -->
<a href="<%= url("/author/#{}") %>"><%= "#{} #{}" %></a>

<!-- Post categories -->
<% @post.categories.each do |category| %>
  <a href="<%= url("/category/#{category.slug}") %>"><%= %></a>
<% end %>

<!-- Publish date -->
<%= @post.published %>

<!-- Post body -->
<%= @post.body %>

Categories, Tags, and Authors

Use Butter's APIs for categories, tags, and authors to feature and filter content on your blog:

class App < Sinatra::Base
  get '/blog' do

    # Get all categories to list in sidebar
    @categories = ButterCMS::Category.all

    erb :index

  get '/author/:slug' do
    @posts = ButterCMS::Post.all({:author_slug => params[:slug]})

    erb :author

  get '/category/:slug' do
    @posts = ButterCMS::Post.all({:category_slug => params[:slug]})

    erb :category


See our API reference for more information about these objects:

RSS, Atom, and Sitemap

Butter generates RSS, Atom, and sitemap XML markup. To use these on your blog, return the generated XML from the Butter API with the proper content type headers.

class App < Sinatra::Base


  get '/feeds/rss' do
    content_type 'text/xml'

  get '/feeds/atom' do
    content_type 'text/xml'

  get '/sitemap' do
    content_type 'text/xml'


Butter doesn't provide an API for comments due to the excellent existing options that integrate easily. Two popular services we recommend are:

Both products are free, include moderation capabilities, and give your audience a familiar commenting experience. They can also provide some additional distribution for your content since users in their networks can see when people comment on your posts. For a minimalist alternative to Disqus, check out RemarkBox or for an open-source option, Isso.


Butter integrates into your front-end so you have complete control over the design of your blog. Use the following CSS as boilerplate for post content styling.

.post-container {
  h1, h2, h3, h4, h5 {
    font-weight: 600;
    margin-bottom: 1em;
    margin-top: 1.5em;

  ul, ol {
    margin-bottom: 1.25em;

    li {
      margin-bottom: 0.25em;

  p {
    font-family: Georgia, Cambria, "Times New Roman", Times, serif;
    font-size: 1.25em;
    line-height: 1.58;
    margin-bottom: 1.25em;
    font-weight: 400;
    letter-spacing: -.003em;

  pre {
    display: block;
    padding: 1em;
    margin: 0 0 2em;
    font-size: 1em;
    line-height: 1.4;
    word-break: break-all;
    word-wrap: break-word;
    color: #333333;
    background-color: #f5f5f5;
    font-family: Menlo, Monaco,Consolas, "Courier New", monospace;

  /* Don't float content on narrow screens */
  @media only screen and (min-width: 720px)  {
    .butter-float-left {
        float: left;
        margin: 0px 10px 10px 0px;

    .butter-float-right {
        float: right;
        margin: 0px 0px 10px 10px;

  /* Image caption */
  figcaption {
    font-style: italic;
    text-align: center;
    color: #ccc;

  /* Inline code highlighting */
  .butter-inline-code {
    padding: 2px 4px;
    font-size: 90%;
    color: #c7254e;
    background-color: #f9f2f4;
    border-radius: 4px;
    font-family: Menlo, Monaco, Consolas, "Courier New", monospace;


To import content from another platform like WordPress or Medium, send us an email.

About Ruby

Ruby is a dynamic, open source programming language with a focus on simplicity and productivity. It has an elegant syntax that is natural to read and easy to write.

Blog Engine for these technologies and more

Ruby, Rails, Node.js, Python, ASP.NET, C#, Flask, Django, Go, PHP, React, Phoenix, Elixir

Get started now

Sign up with Google Sign up with Github