Using Contentful to Back My Static Blog Site

3/24/2018Time to read: 4 min

I recently moved all my blogs to Contentful. It has been a very pleasant experience migrating and writing blogs on Contentful. So I thought I would tribute a post to talk about it. (This post is not sponsored by Contentful)

Contentful is a headless CMS (content management system). Unlike traditional CMS, we either have to host it ourselves or pay to use their service. Traditional CMS usually comes with a lot of restriction on how we build our site. Contentful gives us total freedom on the data structure for our blog and the front end technology stack.

Why not Static Site Generators

I am just writing blogs, why can't I just use static site generator? I used to use static site generator, such as Jekyll and Hexo. To create a new post, I would create a new markdown file in a specific location, and use any text editor of my choice to edit. When I finish the post, I would run a command to generate the static assets and push to Github Pages.

One thing I don't like static site generator is that they have very strict project structure. I built a personal website using whatever technology I like, then I want to add a blog to it. It turned out to be pretty hard. I have to modify my website project structure to what Jekyll or Hexo understand. Finally, I gave up and served them in two different domains.

Static site generator is very hard to customize too. To display the post into our custom format, we need to write templates. Templates contain various fields that a static site generator defines. I was too lazy to read the documentation for all those fields. So I just picked an existing theme.

Entering Contentful

I learned about Contentful when I was checking out the example for GastbyJS. Gatsby is still a static site generator. It has a relatively flexible project structure and total freedom on the look and feel of my site.

But I still don't enjoy manually creating a text file each time I start a new post.

Contentful solved this problem.

Contentful is very easy to get started with. I started by looking at a sample project, and without much effect, I understood how it works.

Defined Content Model

First, we need to define a content model. Those are the types of data we are storing in the database. I only have one type -- Post. We can add any number of fields to the type, and name our fields whatever we want. post content type

Those fields will match the Ajax response when we query for an entry.

Write a Post

Writing a post is as simple as filling out a web form in Contentful. Contentful generates the form based on the content model that we defined. contentful-new-post What's cooler is that all the contents are automatically saved, so we will never worry about not saving our post.

Adding media

Adding an image is super simple too. When I was using static site generator, adding an image usually means the following steps:

  1. Copy the image to a specific location in the project, make sure the filename is different from any other files in the same directory.
  2. Decipher the relative path for the static resource for my site, and construct the URL for the image.
  3. Manually add an image element to markdown file.

With contentful, we can drag and drop local files, or import from other online storage. Contentful save the images in their database and automatically insert a link at our cursor in the post editor. contentful upload media

Calling the API

Posts published on Contentful are not available to general public (unless we want our readers to write a curl command every time they want to read our posts. We need to provide a site that calls the Contentful endpoint to fetch our posts. Contentful provided integration for various languages and they are very easy to integrate into existing projects. contentful-api-doc

What about SEO

What about Search Engine Optimization(SEO)? One of the main advantages of static site generators is: all the post are statically generated. This means web crawler can obtain the content of a page easily without running any JavaScript on the page. This also means, page loads relatively fast, and it will receive a higher score when a search engine indexes it. If we call the Contentful endpoint to get the post data in client side, it will be slower than just serving the assets statically.

The truth is, we can use static site generators with Contentful and get the best of both worlds. Gatsby is one example. There is a Gatsby Contentful plugin that let us fetch all the posts front Contentful during build time and generates all the posts statically.


Contentful is awesome. Once I started writing posts in their interface, I never want to go back to text-editors. Although it requires some setup to integrate into existing projects, the process is very simple. You should try it out!

Software Engineer's Guide on Long Distance Relationship
The Difficulty of Maintaining Routing History in a Single Page App