If you're interested in using Ghost as a "headless CMS" for a fast static site, then you probably have come across websites like Ghost's Gatsby example site and wondered how to make it work for yourself.

Unfortunately, the documentation out there on making static sites with Ghost as a back-end CMS are not good. This is a guide to building your own, ignoring most of the instructions, and telling you only what you need. I've built a similar guide on getting started with the JAMStack using Netlify and Jekyll, if you want to try something even easier!

Both "static sites" and using a "Headless CMS" are making waves in the development community for good reason and I'll explain those quickly here.

In this guide...

  • Why use static site generators rather than WordPress or Ghost
  • Why use a headless CMS rather than just editing your own markdown files (well, that should say enough)
  • Why use Ghost as a Headless CMS
  • Get started and build your Ghost Headless CMS + Gatsby site

Why use Static sites?

Site speed is reason #1. Static sites are the best path to getting a blazing fast site.

Static sites are fast, secure and reliable.

  • Fast: Instead of your web page having to query a database for every visitor, and rely on caching to improve the speed, your web pages are just always HTML with links in them. They need no pre-rendering and are always available in their final form.
  • Secure: As there are no queries to build your page, there's no publicly accessible database or admin portal on the web page that can be hacked. You can hide your CMS installation behind a firewall somewhere and nobody will be able to access it (if they even know where it is).
  • Reliable: HTML always works. It's much harder to make a web server go down if it's just serving HTML.

Static sites are usually built from inputs, which can either be plain markdown files and images, or something more advanced like GraphQL (which is cleanly-presented data that can be ingested and used in a static site).

GraphQL has a few advantages over plain text/images. But the best part is you can pass a lot more data to your blog than just the blog content. You can create fields for authors, dates, titles, metadata, and much more, and send that all to Gatsby, which will create your website.

Gatsby uses GraphQL, which is why I like it.

Why use a Headless CMS?

When building a static site you have three options for how you edit the content.

Classic: Firstly, you can just make HTML and edit it in raw format, using an editor. This is the old school, classic way.

Serve from a built-in CMS: Static sites are served from somewhere. If you use something like Netlify CMS, you get access to a back-end which works like a regular website/blog back-end. It saves data to the filesystem, so all the pages are on GitHub.

Serve from another CMS: You can also connect your installation to any other content management system.

The way this works is:

  • You use your CMS to update your posts and pages whenever you like.
  • Whenever you do, it sends a ping to Netlify saying "yo the whole website updated. You should rebuild the static site."
  • Netlify goes "I have to rebuild! Let me run Gatsby or whatever site generator is being used to rebuild the site and redeploy it"

The benefit of this is you can use any CMS you want. You can use Ghost, or an Google Sheets document, you can use your WordPress site... whatever. Anything that supports GraphQL. You also change your CMS whenever you like, as long as you can move the data around.

Why use Ghost as a Headless CMS?

The Ghost Koenig editor - in dark mode. It's so easy to use.

Ghost has a simple way of creating and managing posts and pages.

If you use Ghost, you know that it's already a great way of building simple blogs. It provides a really clean back-end, with their Koenig editor, and a really nice front-end display through Handlebars themes.

Ghost also produces GraphQL. I mentioned above why GraphQL is a much better data format than just using Markdown, for example.

Gatsby and Netlify is a blazing fast static-site front end. All it needs is a CMS for your back end. This is what Ghost does.

What you'll need to start using Ghost as a headless CMS with Netlify (and Gatsby)

You need four things:

  • A Ghost installation, publicly available
  • A free GitHub account
  • A free Netlify account
  • A domain (or subdomain, like beta.hooshmand.net)

Important: there are lots of things you don't need to do.

  • You DON'T need to download Gatsby, install npm or any software on your local computer.
  • You don't need to run any other software on your server.
  • You don't need to run any git commands or download GitHub desktop.

Firstly, you need a Ghost installation.

The reason you need Ghost still is because you do need to serve your data from somewhere.

The easiest way to install Ghost is to sign up to Ghost here. You get a 14-day free trial. They will take care of everything for you, so all you have to do is write.

The cheapest way is to sign up to DigitalOcean, for $5 a month. You use their "one-click Ghost installation". It's not the easiest because there's some configuration to do, and you now own a server and have to make updates to it. (That link gets you $100 in free credit, and I get $25 as a thank-you, which keeps my server up for five months!)

You may be wondering: "Hey! Ghost publishes the website for me. Why do I have to use it as a headless CMS? It has a head!" Good question. This is best for people who know they want a Headless CMS, because Ghost is the only application with a true visual editor that can spit out GraphXML.

"Can I run the Ghost CMS on my own desktop? Why do I need Digital Ocean?"

You may be tempted to run Ghost on your own desktop. You can do this, and your data will all be on your own desktop. This is easiest if you run Linux on your desktop, but is also doable if you have a Mac or other software running.

The main downside: you won't be able to access your interface from anywhere but your own computer.

Second downside: If you lose your computer, you lose your entire back-end. So if you do this, back up religiously.

Secondly, you need accounts on GitHub and Netlify.

If don't have them, create accounts at GitHub and Netlify.

GitHub is where you're going to store all your code for Gatsby (which builds the front-end) and web page template information.

Netlify is what's going to build your code, using GitHub, and then display it publicly.

If this is sounding like a crazy nest of servers... well, it kind of is. But these services can run independently of each other, and be replaced by other services, so don't worry about them going down.

Third, get a subdomain

Netlify lets you deploy to your own subdomain on Netlify, like xyz.netlify.com. However, you can't use SSL until you have your own domain. That's the main reason you want a subdomain.

Instructions

Here are all the instructions for getting your Gatsby front-end for Ghost to work.

  • Clone the repository. Use GitHub's website (not desktop, not command line) to clone the repository to use as a base for your Gatsby installation and give it a new name in your own repository.
  • Deploy. On your own copy, in your GitHub repository, hit the "Deploy to Netlify" button in it. You'll get redirected a couple of times, being asked to confirm that you want to connect Netlify and GitHub, which of course you do.
  • Put your website's settings into the Gatsby config. Go back into GitHub's interface and edit .ghost.json with your API URL (same as your website with the Ghost installation) and your content API key. You get this by creating a public integration, which you need to do for Netlify to auto-publish anyway.
  • Create the Ghost/Netlify build hook integration. You do this on your own website. (Those likned instructions are pretty good.) These ensure that when you change your site, your Gatsby/Netlify site also changes.
  • Ensure your base URL is https on your website. This is to ensure that images and other links aren't blocked for being insecure mixed content. You may have to go back and configure it. For me this was two instructions:
ghost config url https://my-domain.com

And then

ghost restart

You're good to go!

See my website at https://beta.hooshmand.net. I'm leaving that up as a statically produced backup of my site.

Next steps

Got any questions? Get in touch. I've helped a few people get their first Netlify/Ghost CMS webpage up.