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

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.

Why use Static sites?

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.

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 "Zomg 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?

Look at that editor! 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.

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 the 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, cheapest way to do this is on a DigitalOcean droplet, for $5 a month.

If you want $100 in free credit, sign up here! I get $25 after you've spent $25. You don't have to, but it'd be nice thanks for the effort I put into this blog.

At this point, you have a website and may be wondering why continue... for fun?

"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.


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. Go back into Github's interface and edit .ghost.json with your apiurl (same as your website with the Ghost installation) and my 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. (These 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.


This post is a bit WIP. I'll add more screenshots/instructions as I have time.