DEV Community

Bassel Cheaib
Bassel Cheaib

Posted on

Hosting your Ghost blog on GitHub pages for free

GitHub Pages is an amazing solution for hosting static websites. By using static site generators (like Jekyll, Hugo, Gatsby and many others) you can easily host your personal blog for free there.

But what if you're using a CMS like Ghost to manage your blog? Does that mean that you'll end up having to pay in order to host it?

Well, not necessarily. You can have a local installation of Ghost where you manage everything, then convert it to a static site and publish it for free every time you make changes! Let's get into more details regarding how to do that.


Before you continue with this article, you'll need to complete the following:

  1. Have a running local installation of ghost on your machine. You can do that by following this guide.
  2. If you're a Windows user, you'll need to have the Windows Subsystem for Linux enabled. Here's how you can do it.

Generating the static site

In order to generate the static site, we'll use the Ghost static site generator. With Linux and macOS, this tool can be used directly. However, it's more challenging when you're running on a Windows machine.

The reason for that is that this tool uses wget and grep under the hood. That's where the Windows subsystem for Linux comes to the rescue. If you're not using a windows machine, you can directly skip to step 2.

1. Prepare the environment (Windows only)

Launch the Linux shell and make sure to install npm inside it. To do that, you can run the following command:

sudo apt update && sudo apt install npm
Enter fullscreen mode Exit fullscreen mode

2. Install the tool globally

You can do that by running:

sudo npm install -g ghost-static-site-generator
Enter fullscreen mode Exit fullscreen mode

For windows users, you can now exit the Linux shell by running the exit command.

3. Generate the site

  • Create an empty directory of your choice
  • Open a terminal in this directory (Windows: press SHIFT + Right Click inside this directory then select "Open Linux shell here")
  • Make sure your local ghost installation is running and accessible through the browser. By default it should be running on localhost with the port 2368
  • Run the following command:
gssg --url
Enter fullscreen mode Exit fullscreen mode

This assumes you'll be pushing the code to your main GitHub site repository named, where username is your username (or organization name) on GitHub.

In case you were using a custom URL or even publishing it to other providers like Netlify, change the URL accordingly. The important thing is that it matches the URL where the site will be deployed.

4. Deploy it online

By now, you should have a folder named static inside the folder you created earlier. This is where the entire static website has been generated. All you have to do is push this code to the repository and wait for it to be deployed.

Bonus: if you're using Netlify, you can also just drag and drop this folder into the sites section on your dashboard and it will be automatically deployed.


That's all! Whenever you create new content or update anything, all you need to do is repeat steps 3 and 4.

Small note: There's another possible approach that allows you to make this process even simpler, which is to use Ghost as a headless CMS for a static site generator (Gatsby, Hugo, Next.js, etc). If you'd like to know more about that, you can check the following links:

Top comments (8)

muygalan profile image
Joshua Galan πŸ‘¨β€πŸ’»

I was very excited to get this working and appreciate the write-up. I'm having an issue after converting to static. My entire blog theme seems broken (i.e. the icons are enlarged, colors off, CSS gone berserk etc.) See this video for more details:

Any idea on how to fix this? I actually followed someone else's tutorial before yours and I'm having the exact same results after converting my files for a static site.

Other details:
I'm using the Microsoft Edge browser on Windows 10 with WSL2.

bassel profile image
Bassel Cheaib

When converting to static, you're specifying the domain name that you'll be using when hosing the website. The gssg tool then uses that domain to specify absolute paths for all the links in it (css, images, hrefs, etc).

Due to that, when you're trying to open the site from the local folder before hosting it, the stylesheets won't load and you'll have this problem of the site not looking as intended. However, once hosted, it should work normally.

In case you'd like to see how the website would look like after generating it with the tool, try running this command instead:

gssg --preview
Enter fullscreen mode Exit fullscreen mode
muygalan profile image
Joshua Galan πŸ‘¨β€πŸ’»

Bassel, you win the internet for today. You were spot on with everything. Thanks again for the quick feedback and amazing tutorial. Happy New Year.

Thread Thread
bassel profile image
Bassel Cheaib

Thank you! I'm glad I could help. Happy new year to you too!

bloodreaper741 profile image

What I exactly have to do can you please elaborate? I did gssg --preview still after checking out the preview , after pushing it it still has the same issue.

bloodreaper741 profile image

Hey thanks for making this guide, I have followed through of your post and did exactly what you told but I'm having issue just like Joshua Galan . I did this

gssg --url
gssg --preview and visiting my local site as well.

and then pushed my site to github and it still the same issue.
can you please help. I am on Windows 11 and using WSL 2 Ubuntu 20.04

Edit: Tagged Wrong people

obomighiesophie profile image
sophie Obomighie

Hello, thank you so much for this. Is it normal for the folder generated to be empty? Inside the static, there is a content folder that has nothing inside of it. The folder is different from the folder that has the ghost website and I am sure ghost is running.

devarshishimpi profile image
Devarshi Shimpi

Hey, Great writeup.
It works fine after hosting it. But when posting the link on socials like Twitter, it does embed but not the image, any solutions for that??