CODEX

Make yourself a perfect blogging platform with Ghost and Gatsby

Photo by Anete Lūsiņa on Unsplash

Do you want to have a blogging platform that is both beautiful and manageable? In the past, you are limited the clunky Wordpress or the snappy but not so user friendly static site generators. Recently, however, combining Gatsby and Ghost has finally brought about the revolution we need to take personal blogging to the next level.

Gatsby

Gatsby’s command line interface to generate static HTMLs (Image by author)

Gatsby is basically a static site generator. It is often compared with Jekyll and Hugo. The primary difference is the language they are written in. Gatsby is written in JavaScript using the React library. So, if you are a React developer, it’s the easiest to pickup.

What these site generate have in common is that they all take source files of certain format (e.g. Markdown) and pre-render them into HTML and CSS. The result is a highly optimized website that is built for speed and SEO (Search Engine Optimization).

What’s the big deal? You may ask. Writing HTML is easy enough. However, consider this, if your website serves any image at all. You will want to optimize your images so that they look the best on any device sizes. Now, you are entering the realm of responsive images, something not for the faint of heart. Gatsby does it all for you! 🎉

I have been using Gatsby for little over two years and I have a love and hate relationship with it. On one hand, it is very handy and it creates excellent result. On the other hand, it is lacking a lot in terms of management capabilities. You are basically dealing with Markdown files and JavaScript files. There is also no concept of a lifecycle of a post (i.e. draft vs scheduled vs published).

Ghost

Ghost’s Post Management Screen (Image by author)

Ghost is a modern publishing platform that provides a hosting service. Think of it like a personal Medium. To use their hosting solution, you do have to pay for it. However, the generous Ghost community provides the source code for free and recently, they release a new game changing feature that is reshaping personal blogging. This Ghost front-end allows you to use Ghost as a headless CMS while keeping your favorite front end (i.e. static site generator).

In the remainder of this article, I will talk about this integration.

Integrating Gatsby and Ghost

Gatsby and Ghost Integration (Image by author)

In this diagram, you can see the relationships among the different systems. Each component provides a crucial functionality. My setup looks like this, where go-rest-repeat is the root of my repository.

Gatsby and Ghost integration folder structure (Image by author)

Ghost

To install the Ghost server locally, use the following commands:

$ npm install ghost-cli@latest -g

Then in an empty folder (in my case ghost), type:

$ ghost install local

This will install the current version of Ghost under the folder. Go to the URL: http://localhost:2368/ghost to continue with your setup. I suggest a minimal setup for now as we are still building the system.

While you are there, make sure you also create a Custom Integration point so that you get the Content API key and the Admin API key.

Ghost’s custom integration point. Use it to generate the Content API key and the Admin API Key (Image by author)

We can now move onto Gatsby setup.

Gatsby

Since we are using the Ghost server as a headless CMS, the look and feel of our pre-rendered website is really detached from Ghost itself. In order to preserve as much of the Casper theme as possible, I picked the styxlab/gatsby-starter-try-ghost starter. At the root of my repo, I typed:

$ git clone https://github.com/styxlab/gatsby-starter-try-ghost.git gatsby

API Keys

The starter is setup to retrieve content from Ghost using some GraphQL. To setup the location of the Ghost server, modify the .ghost.json file to include the API keys you have just generated:

{
   "development": {
     "apiUrl": "http://localhost:2368",
     "contentApiKey": "86b94101df2a031b9aaacb0ab9"
   },
   "production": {
     "apiUrl": "http://localhost:2368",
     "contentApiKey": "86b94101df2a031b9aaacb0ab9"
   }
}

Members Plugins

Since we are not running on the Ghost infrastructure, we don’t have the membership functionality. So, we need to remove the members plugin:

$ npm uninstall gatsby-theme-ghost-members

Comment out the same plugin in gatsby-config.js file.

Image Plugins

To host your own images, you need to use the gatsby-rehype-inline-imagesplugin. Use the following command to install it:

$ npm install gatsby-rehype-inline-images

Then, add the plugin into your gatsby-config.js file:

plugins: [
    {
        resolve: `gatsby-transformer-rehype`,
        options: {
            filter: node => (
                node.internal.type === `GhostPost` ||
                node.internal.type === `GhostPage`
            ),
            plugins: [
                {
                    resolve: `gatsby-rehype-ghost-links`,
                },
                {
                    resolve: `gatsby-rehype-prismjs`,
                },
                {
                    resolve: `gatsby-rehype-inline-images`,
                },
            ],
        },
    },    
]

That is all the setup you need on Gatsby. When you run gatsby build or gatsby develop next time, it will query the Ghost server, retrieve all of the posts, download images, and pre-render the static HTMLs into the /public folder.

Netlify

Last but not least, we will deploy our shiny website onto a CDN. We are grateful to have Netlify hosting our content for free. First, let’s install the Netlify command line interface:

$ npm -g install netlify-cli

When you are in your project folder, login to Netlify with:

$ netlify login

Finally, deploy to Netlify ( -p means production):

$ netlify deploy -p

Netlify will proceed to ask you a few questions. Once you are done answering, your site will be uploaded and reachable on the internet.

Tips

Remove unused images

Ghost accumulates uploaded images even when they are not used. So, before I backup, I run the ghost-purge-images command to remove unused images. You can install this tool using:

$ npm install -g ghost-purge-images

Use the following command to purge these unused images:

$ ghost-purge-images purge --content-key=<content API Key> --admin-key=<Admin API Key>

Backing up your work

You don’t want to lose your hard work in case something goes wrong with your company. Make sure everything under the ghost/content folder is included in your backup solution. I just make sure it's included in my repository.

Conclusion

The combination of Gatsby, Ghost, and Netlify provides a free personal blogging platform. The ease of use overweighs the little up front setup time. For bloggers who want complete control, there is a fear of locking down to the Ghost database. For the rest of us, however, this can a perfect setup.

ps. To see a sample of this setup, visit my personal webpage: https://www.gorestrepeat.com