Using Contentful's CMS with static site generators

More and more developers are jumping on the "go static train", and rightfully so. Static pages are fast, lightweight, they scale well. They are more secure and simple to maintain, allowing you to focus all your time and effort on the user interface. Often times, this dedication really shows.

It just so happens that static site generators are mostly loved by developers, but not by the average Joe. They do not offer What-You-See-Is-What-You-Get (WYSIWYG) so previewing content on demo sites may take an update cycle, they are often based on markdown text files, and they require some knowledge of modern-day repositories.

Moreover, when teams are collaborating, things can quickly become complicated. Has this article already been proof-read or reviewed? Is this input valid? Are user permissions available, e.g. for administering, adding and removing team members? Can this article be published at a future date? How can a large repository of content be categorized, organized, and searched? All these requirements have previously been more or less solved within the admin area of your CMS. But of course, with all the baggage that made you leave the appserver-app-database-in-one-big-blob stack in the first place.

An alternative is decoupling the content management aspect from the system. And then replacing the maintenance prone server with a cloud based web service offering. Effectively, instead of your old CMS, you move to a content infrastructure world, with a content APIs to deliver all your content. That way, you get the all the benefits of content management features while still being able to embrace the static site generator mantra.

It so happens that our content infrastructure is offering just that kind of content APIs. We have a service that:

• from the ground up has been designed to be fast, scalable, secure, and offer high uptime, so that you don’t have to worry about maintenance ever again.
• offers a powerful editor and lots of flexibility in creating templates for your documents that your editors can reuse and combine, so that no developers resources are required in everyday writing and updating tasks.
• separates content from presentation, so you can reuse your content repository for any device platform your heart desires. That way, you can COPE ("create once, publish everywhere").
• offers webhooks that you can use to rebuild your static site in a fully automated fashion every time your content is modified.

With a little effort, API queries, and JSON transformations, you can integrate Contentful in any SSG you can imagine. In practice, our ecosystem team and some highly appreciated community developers have already created some integrations with the following popular static site generators:

• Gatsby (React)
• Jekyll (Ruby)
• Middleman (Ruby)
• Metalsmith (Node.js)
• Roots (Node.js)

In order to be completely removed from everyday site management and maintenance, we suggest following the approach from Carrot Creative. In addition to Contentful, you will need a hoster that supports webhooks and is capable of starting builds and deploying sites/apps.

1. On your host: Create a webhook endpoint that starts a new build and deploys a project whenever it receives a POST request.
2. On Contentful: Create a webhook with the host endpoint as destination URL.

This way, whenever a writer creates or updates content, the host will receive a webhook and deploy. That way, a couple of minutes from publishing, the new content is live.

We strongly suggest having a test site/app. Since static site generators do not offer the benefits of WYSIWYG, deploying to a separate domain that is only known to your editors will give them the chance to preview if the site is exactly looking like they want it to. For this specific purpose, Contentful also offers a preview API. Also, do not forget to restrict search engines on that preview domain (e.g. by excluding all robots via a robots.txt file, or by setting an htaccess restriction).

For deployment, use a store that allows for some basic HTTP header configuration. Over time, you may want to eliminate some content items or refactor content, and in the course of doing so you may delete old URLs and create new ones. Be mindful in setting 301 redirects so as not to lose all those referrer visitors as well as the link equity that made you popular in search engines.

Sign up to a Contentful account now! There is free testing plan which will most likely suffice for most small projects. For bigger projects, the paid plans have a 30 day trial period.

Check out our guide on Automated rebuild and deploy with CircleCI and Webhooks for a real-world example using Jekyll or Middleman.