Learn how to build a Gatsby blog using . The code examples in this article let you combine Gatsby and ButterCMS in just a few minutes, no matter if you are a beginner or an expert. ButterCMS Why Gatsby and ButterCMS? is a static site generator based on React and GraphQL. ButterCMS is a headless CMS and blogging platform. What does that mean and why should you use them? Gatsby A static site (HTML, CSS, and JavaScript) is fast, secure and flexible. There is no database or server-side code that attackers can exploit. A static site generator pulls data from APIs, databases or files and generates pages using templates. As a developer, you probably want to write your content as Markdown files. However, if your static site’s content has to be managed by non-developers, they’ll prefer a CMS. offers a read-only API, that can be read by your static site generator. A headless CMS Gatsby combines React, , webpack and other front-end technologies to provide a great developer experience. It’s a great choice if you are already familiar with and JSX. ButterCMS allows you to add a CMS to your Gatsby sites without having to worry about hosting, security, or performance. You can focus on implementing your front-end. GraphQL React Now that we know the benefits of Gatsby and ButterCMS, let’s get started! Setup First, create a . You’ll be provided with an API token and an example blog post. You’ll need both for this tutorial. ButterCMS account Next, install the Gatsby CLI. npm install --global gatsby-cli You can then create a new site from the official starting template. If you navigate to the directory and run , Gatsby will start a hot-reloading server at gatsby develop [http://localhost:8000/](http://localhost:8000/.) . This way, you don’t have to refresh your page as Gatsby injects new versions of the files that you edited at runtime. gatsby new gatsby-site https://github.com/gatsbyjs/gatsby-starter-defaultcd gatsby-sitegatsby develop Posts When building with Gatsby, you access your data via the query language . There are many official and community plugins that fetch data from remote or local locations and make it available via GraphQL. These plugins are called “source plugins” and there is already a you can install. GraphQL Gatsby Source Plugin for ButterCMS npm install --save gatsby-source-buttercms Add the plugin to your and copy and paste your ButterCMS API token. gatsby-config.js module.exports = { plugins: [ { resolve: 'gatsby-source-buttercms', options: { authToken: 'your_api_token' } } ]} After this change, you might have to restart the hot-reloading server ( ) before you can test the GraphQL fields and types the plugin is providing. gatsby develop Head to GraphiQL, the in-browser IDE for exploring GraphQL, at and explore the and fields. http://localhost:8000/___graphql butterPost allButterPost { allButterPost { edges { node { title body } } }} The plugin maps all JSON fields documented in the to GraphQL fields. Butter CMS API Reference Add a list of your blog posts Your ButterCMS data can now be queried in any Gatsby page or template. You can start by creating a and adding a list of your blog posts. src/pages/blog.js import React from 'react'import { graphql, Link } from 'gatsby'import Layout from '../components/layout'const BlogPage = ({ data }) => { const posts = data.allButterPost.edges .map(({ node }) => { return <Link key={node.id} to={`/${node.slug}`}>{node.title}</Link> }) return <Layout>{posts}</Layout>}export default BlogPageexport const pageQuery = graphql` query { allButterPost { edges { node { id slug title } } } } The page is now available at . You can also edit the existing if you want to have the list on your home page. /blog src/pages/index.js Add pages for your blog posts Generating a page for each of your posts requires you to create a template at . You’ll then edit in your project’s root folder and use , specifically the and its . src/template/post.js gatsby-node.js Gatsby's Node APIs createPages API createPage action **src/templates/post.js** import React from 'react'import { graphql } from 'gatsby'import Layout from '../components/layout'export default function Template({ data }) { const { title, date, body } = data.butterPost return ( <Layout> <h1>{title}</h1> <h2>{date}</h2> <div dangerouslySetInnerHTML={{ __html: body }} /> </Layout> )}export const pageQuery = graphql` query($slug: String!) { butterPost(slug: { eq: $slug }) { title date body } } **gatsby-node.js** const path = require('path') exports.createPages = ({ actions, graphql }) => { const { createPage } = actions const template = path.resolve(`src/templates/post.js`) return graphql(` { allButterPost { edges { node { slug } } } } `).then(result => { if (result.errors) { return Promise.reject(result.errors) } result.data.allButterPost.edges.forEach(({ node }) => { console.log(node); createPage({ path: `/blog/${node.slug}`, component: template, context: { slug: node.slug } }) }) })} Categories, Tags, and Authors Use the argument against your ButterCMS categories, tags, and authors to feature and filter the content of your blog. filter { allButterPost(filter: { tags: { elemMatch: { slug: { in: "example-tag" } } } }) { edges { node { id title } } }} Pages If you want to add ButterCMS pages to your blog, add a list of page slugs to your and follow the same steps as for your blog posts, using the and GraphQL fields. gatsby-config.js butterPage allButterPage ButterCMS automatically generates a slug when you create a new page: A page titled gets an slug, which is shown below the page title in the ButterCMS editor. You can add these slugs to your : Example Page example-page gatsby-config.js module.exports = { plugins: [ { resolve: 'gatsby-source-buttercms', options: { authToken: 'your_api_token', pages: [ 'homepage' ] } } ]} { allButterPage(filter: {slug: {eq: "homepage"}}) { edges { node { slug } } }} You can also specify a page type in your : gatsby-config.js module.exports = { plugins: [ { resolve: 'gatsby-source-buttercms', options: { authToken: 'your_api_token', pageTypes: [ 'products' ] } } ]} To get all pages for a given type you can then use the following GraphQL query: { allButterPage(filter: {page_type: {eq: "products"}}) { edges { node { slug } } }} Conclusion We have learned how to use a Gatsby source plugin to convert headless CMS data to Gatsby nodes, how to query those nodes with GraphQL, and how to create pages. This should give you a head start when building a Gatsby blog with ButterCMS. Where to go from here? You could use what you’ve learned and add a page that lists your categories and tags. If you already have a lot of content, you might want to add pagination to your list of blog posts. You can do so by using the and arguments of the and fields in GraphQL. limit skip allButterPost allButterPage If you need help after reading this, contact ButterCMS’s support via or livechat. email The is an open-source community plugin for Gatsby. If you want to contribute to the source plugin, open a . If you have found a bug, open a . Gatsby Source Plugin for ButterCMS GitHub pull request GitHub issue If you’ve enjoyed this article, please help it spread by clapping below! For more content like this, follow us on Twitter and subscribe to our blog. is a headless CMS that lets you build CMS-powered apps using any programming language including , , , , , , , , , , , , , , , , and And if you want to add a blog or CMS to your website without messing around with Wordpress, you should try Butter CMS . ButterCMS Ruby Rails Node.js Python ASP.NET Flask Django Go PHP Laravel Angular React Elixir Phoenix Meteor Vue.js Gatsby.js
