Building with Gatsby, Contentful & Netlify

This page's sources are hosted on GitHub if you want to look into the sources. We are using Gatsby 2 already.

When we started building this website we created a static website with webpack and html-loader to get things online quickly. Netlify was already involved so deploying was no problem but updating itself was a cumbersome as only us developers were able to do so through code & git.

There was no really human readable source files. I decided to look into some static page generators. I used ruby-based middleman years ago but I knew there are more powerful and recent generators out there. Ghost, Hugo, Jekyll and Gatsby are the ones I wanted to checkout for a long time. I ended up with Gatsby.

Gatsby & JAMstack

Gatsby is a static website generator based on React with a rich plugin ecosystem. It's based on the JAMstack. The name comes from JavaScript (J) that access APIs (A) to create static markup (M). There is more behind the JAMstack philosophy so make sure you check the website.

Gatsby uses GraphQL to access any API you can imagine. We use contentful for example but you can also use your local disk as an API to read in markdown files for example. Or do you have a Wordpress blog? You can use it as a data source too!

If you have never seen GraphQL, here a quick example (from our Event Overview on our start page)

allContentfulEvents(sort: {fields: [date], order: ASC}) {
    edges {
      node {
        dateShort: date(formatString: "MMM DD")
        dateTitle: date(formatString: "MMM DD, YYYY")

That query returns JSON and the data structure will be exactly as you see it. Gatsby and its plugins are doing the necessary work that you are only left writing GraphQL queries. It's really amazing!

Our lovely Stack

I was amazed from the first moment tinkering around with Gatsby. That's why I want to talk about what we are using now and what made me so cheerful about it.


Contentful is really a joy to work with. Create your content model (like blog post, page or author) and switch over to the content area to create instances of them. Seconds later you jump back to your local gatsby installation and you can already query the data in your own application.

Image Processing

Do you know the SVG image tracing technique? I didn't but gatsby educated me. That tweet is the origin of this technique. When you do lazy loading you usually load a lowres image before fetching any higher resolution. Gatsby's default is to embed and display a minimal and blurred version of your image in your page before it gets replaced.

By replacing the blurred version with a SVG outline you get the feeling to see more details from the beginning while maintaining a small footprint. And the best thing? Gatsby already delivers a working solution so you can start using it today.

The mentioned lazy loading behavior in Gatsby is also convenient. You only need to parts: gatsby-image and its special <Img/> tag together with a GraphQL query. This will assemble everything needed to lazy load an image coming from contentful. If you wanted to display a traced svg you would make some changes but still: those two parts would be enough. I love this simplicity. You can read Working With Images In Gatsby for more details about image processing in gatsby.

	fluid={image.fluid} />
contentfulBlogPost {
	image {
	    fluid(maxWidth: 600){


I already mentioned we are using netlify. It's like Heroku and other "git based deployment" tools but much more convenient (speaking of the Heroku I used some years ago).

You get branch and PR deployment. Webhooks trigger the deployment so you can deploy on any git update but also if you publish something in contentful (if you registered contentful's webhook in netlify).

I created a staging environment and by using netlify's deploy context I switch the contentful tokens to use the Contentful Deploy API so I can see all drafts from contentnful on our staging.

That's the part of our netlify.toml. staging is the branch name and not some preset of netlify.

  environment = { FULL_PREVIEW = "true" }

Markdown Support

I love to write in Markdown that's why I was amazed that I could create Markdown fields with previews in contentful. The data itself is not transformed by contentful. It's your duty and that's where the fun begins. Gatsby has a lot of Markdown processing plugins. We are using:

  • gatsby-transformer-remark (gatsby)
  • gatsby-remark-prismjs (gatsby)
  • gatsby-remark-component (JS)
  • rehype-react (JS)

The remark transformer enables us to use GraphQL to transform markdown sources into html. Looks like this. body is your own markdown field in contentful.

contentfulBlogPost {
	body {
	    childMarkdownRemark {

The three parts html, htmlAst and excerpt are possible values you can query. html contains the transformed html. htmlAst is generated by gatsby-remark-component and can be used to map custom react components to markdown html tags. This allows us to use our styled components in the markdown content instead of creating global styles.

new rehypeReact({
  createElement: React.createElement,
  components: {
    "a": Link,
    "p": Copy,
    "h1": HeadlineContent,
    "h2": HeadlineSection,

Gatsby Node APIs

This is about the file gatsby-node.js which is multi-functional place. Basically everything that is running in node — the generating part of gatsby.

You will find there lifecycle callbacks like onCreateDevServer or onPreBuild but also functions like createPages.

createPages is what you use to dynamically create pages from APIs (like Markdown files or contentful). You use GraphQL to query for the data and loop over it calling createPage() inside the createPages function. This will create pages under a URL you define and from a template you can define too.

With this mechanic it's easy to create a set of blog posts and pages from our contentful pages. We could have mixed it too. Like creating our Content Pages from Markdown files and our blog from a Wordpress REST API.


The JAMstack is fun and I think Gatsby with contentful is a very good example of it. It feels really fast in terms of development cycles and actual web performance. I can only encourage you to try it out. Or pick any of those things and give it a try during your next break: GraphQL, Gatsby, Contentful, Netlify.

Aktualisiert: 25.Okt. 2018,  Erstellt: 10.Okt. 2018