Run this in your commandline:

npm install buttercms --save

Butter can also be loaded using a CDN:

<script src="https://cdnjs.buttercms.com/buttercms-1.1.4.min.js"></script>

Or if you're using Yarn:

yarn install buttercms

The source code is available on Github.

Set your API token:

var butter = require('buttercms')('your_api_token');

Or if using ES6 syntax:

import Butter from 'buttercms';
const butter = Butter('your_api_token');

Then run:

butter.post.list({page: 1, page_size: 10}).then(function(response) {
  console.log(response)
})

This API request fetches our blog posts. Your account comes with one example post which you'll see in the response. If you get a response it means you're now able to connect to our API.

Contents

Headless CMS

ButterCMS is a headless CMS that lets you manage content using our dashboard and integrate it into your tech stack of choice with our content APIs. You can use ButterCMS for new projects as well as add it to existing codebases.

If you're familiar with Wordpress, see how ButterCMS compares to WordPress.

ButterCMS provides a user-friendly UI for managing marketing sites, blogging, and custom content scenarios. We can be used for SEO landing pages, customer case studies, company news & updates, events + webinar pages, education center, location pages, knowledgebases, and more.

We are different from a traditional CMS like Drupal or Wordpress in that we're not a large piece of software you need to download, host, customize, and maintain. Instead we provide easy to consume, performant content API's that you add to your application.

For example, if you wanted to enable a non-technical person to be able to add customer case study pages to your marketing site, you might create a Case Study Page Type to represent these pages. The non-technical person would be able to manage these pages from our dashboard and the JSON API output would look something like this:

{  
  "data": {
    "slug": "acme-co-case-study",
    "fields": {
      "seo_title": "Acme Co Customer Case Study",
      "seo_description": "Acme Co saved 200% on Anvil costs with ButterCMS",
      "title": "Acme Co loves ButterCMS",
      "body": "<p>We've been able to make anvils faster than ever before! - Chief Anvil Maker</p>"
    }
  }
}

Use Postman to experiement

Postman is a great tool for experiementing with our API. We wrote a post about it here. Once you've installed Postman, click this button to quickly add our end point Collection to your Postman.

Run in Postman

Webhooks

Webhooks are a powerful feature that allow you to notify your internal systems whenever content in ButterCMS has changed. You can learn more about Webhooks in this blog post.

Image Transformation

ButterCMS has integrated with a rich image transformation API called Filestack. This allows you to modify your uploaded images in dozens of ways. Everything from resizing, cropping, effects, filters, applying watermarks and more. Check out Filestack full documentation for more detail.

After you upload an image to ButterCMS, it's stored on our CDN. To create a thumbnail, here's an example:

Original URL = https://cdn.buttercms.com/zjypya5tRny63LqhHQrv

Thumbnail URL = https://fs.buttercms.com/resize=width:200,height:200/zjypya5tRny63LqhHQrv

Resizing is just one of the many different transformations you can do to your images. Refer to the Filestack docs for full details.

Localization

ButterCMS has full support for localization of your content. Locale names and keys are completely customizable and there's no limit to the number of locales you can have. View our API Reference to learn how to query by locale.

Table of Contents

Introduction

Quickly launch a new marketing site or add CMS-powered pages to your existing site using our Pages.

Create a Single Page

Adding a CMS-powered page to your app involves three easy steps:

  1. Create the Page structure
  2. Populate the content
  3. Integrate into your application

If you need help after reading this, contact us via email or livechat.

Create the Page Structure

Create a new Page and define it's structure using our Page Builder. Let's create an example homepage.

PagesNewSinglePage

Populate the Content

Then populate our new page with content. In the next step, we'll call the ButterCMS API to retrieve this content from our app.

PagesNewSinglePageContent

Integrate into your application

With your homepage defined, the ButterCMS Pages API will return it in JSON format like this:

{
  "data": {
    "slug": "homepage",
    "fields": {
      "seo_title": "Anvils and Dynamite | Acme Co",
      "headline": "Acme Co provides supplies to your favorite cartoon heroes.",
      "hero_image": "https://cdn.buttercms.com/c8oSTGcwQDC5I58km5WV",
      "call_to_action": "Buy Now",
      "customer_logos": [
        {
          "logo_image": "https://cdn.buttercms.com/c8oSTGcwQDC5I58km5WV"
        },
        {
          "logo_image": "https://cdn.buttercms.com/c8oSTGcwQDC5I58km5WV"
        }
      ]
    }
  }
}

This guide uses the Express framework and EJS templates but Butter integrates with any Node.js server and templating engines like Jade, Mustache, and React. To create these page in our app, we create a route that fetches content for the homepage. Here's what the code looks like:

app.js:

var express = require('express');
var butter = require('buttercms')('your_api_token');

var app = express()

app.set('view engine', 'ejs');

// Routes
app.get('/', function() {
  butter.page.retrieve("*", "homepage").then(function(resp) {
    var page = resp.data.data;

    res.render('homepage', {
      homepage: page.fields
    })
  });
});

views/homepage.ejs:

<html>
  <head>
    <title><%= homepage.seo_title %></title>
    <meta property="og:title" content="<%= homepage.facebook_open_graph_title %>" /> 
  </head>
  <body>
    <h1><%= homepage.headline %></h1>
    <img width="100%" src="<%= @homepage.hero_image %>">
    <button><%= @homepage.call_to_action %></button>
    <h3>Customers Love Us!</h3>
    <!-- Loop over customer logos -->
    <%= @homepage.customer_logos %>
  </body>
</html>

That's it! If you browse to your homepage you'll see your homepage populated with the content you created in Butter.

Create multiple pages using Page Types

Overview Video

Let's say you want to add a set of customer case study pages to your marketing site. They all have the same structure but the content is different. Page Types are perfect for this scenario and involves three easy steps:

  1. Create the Page Type structure
  2. Populate the content
  3. Integrate into your application

If you need help after reading this, contact us via email or livechat.

Create the Page Type structure

Create a Page Type to represent your Customer Case Study pages:

PagesNewPageType1

After saving, return to the configuration page by clicking the gear icon:

PagesNewPageType2

Then click on Create Page Type and name it "Customer Case Study". This will allow us to reuse this field configuration across multiple customer case study pages:

PagesNewPageType3

Populate the Content

Then populate our new page with content. In the next step, we'll call the ButterCMS API to retrieve this content from our app.

PagesNewSinglePageContent

Integrate into your application

With a case study defined, the ButterCMS Pages API will return it in JSON format like this:

{
    "data": {
        "slug": "acme-co",
        "fields": {
            "facebook_open_graph_title": "Acme Co loves ButterCMS",
            "seo_title": "Acme Co Customer Case Study",
            "headline": "Acme Co saved 200% on Anvil costs with ButterCMS",
            "testimonial": "<p>We've been able to make anvils faster than ever before! - <em>Chief Anvil Maker</em></p>\r\n<p><img src=\"https://cdn.buttercms.com/NiA3IIP3Ssurz5eNJ15a\" alt=\"\" caption=\"false\" width=\"249\" height=\"249\" /></p>",
            "customer_logo": "https://cdn.buttercms.com/c8oSTGcwQDC5I58km5WV",
        }
    }
}

This guide uses the Express framework and EJS templates but Butter integrates with any Node.js server and templating engines like Jade, Mustache, and React. To create these pages in our app, we create a dynamic route that fetches content for the page by using a URL parameter. Here's what the code looks like:

app.js:

var express = require('express');
var butter = require('buttercms')('your_api_token');

var app = express()

app.set('view engine', 'ejs');

// Routes
app.get('/customers/:slug', function() {
  butter.page.retrieve("customer_case_study", params.slug).then(function(resp) {
    var page = resp.data.data;

    res.render('case_study', {
      case_study: page.fields
    })
  });
});

views/case_study.ejs:

<html>
  <head>
    <title><%= case_study.seo_title %></title>
    <meta property="og:title" content="<%= case_study.facebook_open_graph_title %>" /> 
  </head>
  <body>
    <h1><%= case_study.headline %></h1>
    <img width="100%" src="<%= case_study.customer_logo %>">
    <p><%= case_study.testimonial %></p>
  </body>
</html>

That's it! If you browse to /customers/acme-co, you'll see the Page you created in Butter.

If you need help after reading this, contact us via email or livechat.

Table of Contents

Introduction

Content Fields are global pieces of content that can be managed by your team. They can be used for content that spans multiple pages (header, footer) or platforms (desktop, mobile). Each content field has unique ID for querying via our API. Let's see how you can use them to power a knowledge base. Again Content Fields are great for content that can appear in multiple places so this knowledge base could appear on your website and mobile app. This example will focus on your website.

Two-step process:

  1. Setup custom content fields in Butter
  2. Integrate the fields into your application

If you need help after reading this, contact us via email or livechat.

Setup content fields

Let's suppose we want to add a CMS to a static FAQ page with a title and a list of questions with answers. Here's the initial code for the server and static page with the Butter API client installed:

app.js:

var express = require('express');
var butter = require('buttercms')('your_api_token');

var app = express()

app.set('view engine', 'ejs');

// Routes
app.get('faq', function() {
  res.render('faq')
});

views/faq.ejs:

<h1>FAQ</h1>

<ul>
  <li>
    <h4>When was this company started?</h4>
    <p>2014</p>
  </li>
  <li>
    <h4>What forms of payment do you accept?</h4>
    <p>Credit cards and checks.</p>
  </li>
</ul>

Making your content dynamic with Butter is a two-step process:

  1. Setup custom content fields in Butter
  2. Integrate the fields into your application

To setup custom content fields, first sign in to the Butter dashboard.

Create a new workspace or click on an existing one. Workspaces let you organize content fields in a friendly way for content editors and have no effect on development or the API. For example, a real-estate website might have a workspace called "Properties" and another called "About Page".

Once you're in a workspace click the button to create a new content field. Choose the "Object" type and name the field "FAQ Headline":

After saving, add another field but this time choose the "Collection" type and name the field FAQ Items:

On the next screen setup two properties for items in the collection:

Now go back to your workspace and update your heading and FAQ items.

Integrate your app

To display this dynamic content in our app, we fetch the fields with an API call and then reference them in our view. Here's what the code looks like:

app.js:

var express = require('express');
var butter = 'require(buttercms')('your_api_token');

var app = express()

app.set('view engine', 'ejs');

// Routes
app.get('faq', function() {
  butter.content.retrieve(["faq_headline", "faq_items"]).then(function(resp) {
    var content = resp.data.data;

    res.render('faq', {
      content: content
    })
  });
});

views/faq.ejs:

<h1><%= content.faq_headline %></h1>

<ul>
  <% content.faq_items.forEach(function(item) { %>
    <li>
      <h4><%= item.question %></h4>
      <p><%= item.answer %></p>
    </li>
  <% }); %>
</ul>

That's it! The values entered in the Butter dashboard will immediately update the content in our app.

If you need help after reading this, contact us via email or livechat.

Table of Contents

Introduction

Learn how to quickly build a custom blog with great SEO. Butter integrates with any Node.js server and templating engines like Mustache, Jade, and React. This guide uses the Express framework and EJS templates. Full working example code is available on Github and as this Heroku Deploy Button:

Deploy

To get started even quicker, here's a set of sample blog templates you can use.

If you need help after reading this, contact us via email or livechat.

Create a New Sample Project using our CLI for Express.js

If you'd like to create a sample blog project, you can use our CLI to quickly create a new Express blog project that's already integrated with ButterCMS. After you've installed it, run:

$ buttercms generate:blog --for=express

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.

var express = require('express');
var butter = require('buttercms')('your_api_token');
var app = express()

app.set('view engine', 'ejs');

app.get('/blog', renderHome)
app.get('/blog/p/:page', renderHome)

app.listen(3000)

function renderHome(req, res) {
  var page = req.params.page || 1;

  butter.post.list({page_size: 10, page: page}).then(function(resp) {
    res.render('index', {
      posts: resp.data.data,
      next_page: resp.data.meta.next_page,
      previous_page: resp.data.meta.previous_page
    })
  })
}

Next we'll create an EJS template for displaying our posts and pagination links. This guide uses EJS templates but Butter works with any templating engine like Jade, Mustache, and React. If you need help after reading this, contact us via email or livechat.

<h2>Blog</h2>

<% posts.forEach(function(post) { %>
  <a href="/blog/<%= post.slug %>"><%= post.title %></a> by <%= post.author.first_name %> <%= post.author.last_name %>
  <br>
<% }); %>

<% if (previous_page) { %>
  <a href="/blog/p/<%= previous_page %>">Prev</a>
<% } %>

<% if (next_page) { %>
  <a href="/blog/p/<%= next_page %>">Next</a>
<% } %>

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

app.get('/blog/:slug', renderPost)

function renderPost(req, res) {
  var slug = req.params.slug;

  butter.post.retrieve(slug).then(function(resp) {
    res.render('post', {
      title: resp.data.data.title,
      post: resp.data.data,
      published: new Date(resp.data.data.published)
    })
  })
}

The template for displaying a full post includes information such as author and publish date. See a full list of available post properties in our API reference.

<h2><%= post.title %></h2>

Published <%= published.getDate() %>/<%= published.getMonth()+1 %>/<%= published.getFullYear() %>

<% if (post.categories.length > 0) { %>
  in 
  <% post.categories.forEach(function(cat) { %>
    <a href="/category/<%= cat.slug %>"><%= cat.name %></a> 
  <% }); %>
<% } %>

<br>

<%= post.author.first_name %> <%= post.author.last_name %>

<div>
  <%- post.body %>
</div>

Categories, Tags, and Authors

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

app.get('/category/:slug', renderCategory)

function renderCategory(req, res) {
  var slug = req.params.slug;

  butter.category.retrieve(slug, {include: 'recent_posts'})
    .then(function(resp) {
      res.render('category', {
        title: resp.data.data.name,
        category: resp.data.data
      })
    })
}

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.

app.get('/rss', function(req, res) {
  res.set('Content-Type', 'text/xml');

  butter.feed.retrieve('rss').then(function(resp) {
    res.send(resp.data.data)
  })
});

app.get('/atom', function(req, res) {
  res.set('Content-Type', 'text/xml');

  butter.feed.retrieve('atom').then(function(resp) {
    res.send(resp.data.data)
  })
});

app.get('/sitemap', function(req, res) {
  res.set('Content-Type', 'text/xml');

  butter.feed.retrieve('sitemap').then(function(resp) {
    res.send(resp.data.data)
  })
});

Comments

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.

Social Sharing

To maximize sharing of your content, we recommend using a free tool called AddThis.

They provide an attractive and easy to integrate social sharing widget that you can add to your website.

Social Share Buttons

CSS

Butter integrates into your front-end so you have complete control over the design of your blog. The rich text editor allows for formatting that you'll want to make sure you have styled. The boilerplate CSS covers most cases:

.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;
  }

  /* Responsive default image width */
  img {
    max-width: 100%;
    height: auto;
  }

  /* Responsive floating */
  @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 */
  p code {
    padding: 2px 4px;
    font-size: 90%;
    color: #c7254e;
    background-color: #f9f2f4;
    border-radius: 4px;
    font-family: Menlo, Monaco, Consolas, "Courier New", monospace;
  }

  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;
  }
}

Migration

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

Get started now

Sign up with Google Sign up with Github
or