(this post is originally published at http://zzamboni.org/post/hosting-a-ghost-blog-in-github/)

When I was planning the reboot of my website, I seriously considered using Ghost. It has a very nice UI, beautiful and usable theme out of the box, and a very active community. Eventually I decided to use Hugo, but in the process discovered that it is possible to host a statically-generated Ghost website using GitHub Pages.

Overview

The general approach, described in multiple articles I found, is the following:

1. Install and run Ghost locally
2. Edit/create your content on your local install
3. Create a static copy of your Ghost site by scraping it off the local install.
4. Push the static website to GitHub Pages

So far, so good. It makes sense. But all those articles share one thing: they suggest using a tool called buster which, as far as I can tell, it's a web-scraping tool, specialized for Ghost. However, it has a number of limitations–for example, it does not slurp Ghost static pages, and it hasn't been updated in a very long time (there's a fork with somewhat more recent activity).

I found the use of buster puzzling, since there is a perfectly mature, functional and complete tool for scraping off a copy of a website: good old trusty wget. It is included (or easily available) in most Unix/Linux distributions, it is extremely powerful, and has features that make it really easy to create a local, working copy of a website (including proper translation of URLs). I used it to create the static archive of my old blog, BrT, when I decided to retire its WordPress backend years ago.

Another thing I found is that most instructions suggest storing only the generated website in your GitHub repository. I prefer keeping the source files and the generated website together. GitHub pages allows serving the website from different sources, including the repo's gh-pages branch, its master branch, or the /docs directory in the master branch. Personally, I prefer using the /docs directory since it allows me to keep both the source and the generated website in the same place, without any branch fiddling.

So, without further ado, here are the detailed instructions. I ran these on my Mac, but most of them should work equally well on Linux or any other Unix-like system.

Install Ghost

1. Download Ghost (version 1.7.1 as of this writing):

   cd ~/tmp # or some other suitable place
   wget https://github.com/TryGhost/Ghost/releases/download/1.7.1/Ghost-1.7.1.zip
   

2. Unpack it in a suitable directory, initialize it as a GitHub repository and commit the Ghost plain install (to have a baseline with the fresh install):

   mkdir test-ghost-blog
   cd test-ghost-blog
   unzip ../Ghost-1.7.1.zip
   git init .
   git add .
   git commit -m 'Initial commit'
   

3. Install the necessary Node modules, update the git repository:

   npm install
   git add .
   git commit -m 'Installed Node dependencies'
   

4. Install knex-migrator, needed for the DB initialization:

   npm install -g knex-migrator
   

5. Initialize the database and start Ghost (knex-migrator may give a "Module version mismatch" message, but it seems to work OK anyway):

   knex-migrator
   npm start
   

6. Your blog is running! You can visit it at http://localhost:2368/:
   

7. Go to http://localhost:2368/ghost, create your user and set up your blog info:
   
   You may want to use an email address you don't mind being public. See "Security Considerations" below.

8. Start creating content!
   

9. Update the git repository:

   git add .
   git commit -m 'Finished local Ghost setup'
   

Export website

Now that you have your blog set up locally, we need to generate a static copy that can be published to GitHub. For this we will use the wget command. I gathered the correct options from this blog post by Ilya a few years ago, although it's not too hard to deduct them from the wget man page.

1. We will publish the blog from the docs directory of our repository, so that's where we need to store the static copy:

   wget -r -nH -P docs -E -T 2 -np -k http://localhost:2368/
   

   This command will crawl the entire site and create a static copy of it under the docs directory. You can open the file docs/index.html in your web browser to verify.

2. Add the generated pages to the git repository:

   git add docs
   git commit -m 'Initial commit of static web site'
   

Push to GitHub

We can finally create our GitHub repo and push the contents to it.

1. Create the repository. I'm using here the hub command, but of course you can also do it by hand in the GitHub website (in this case you need to add the git remote by hand as well):

   hub create 
   

2. Push the local repository to GitHub (this includes both the Ghost source and the generated website under docs):

   git push -u origin master
   

Publish!

Now all we need to do is enable GitHub Pages on our repository, so that the contents under docs gets published.

1. Go to your repository's "Settings" screen:
   

2. Scroll down to the "GitHub Pages" section and choose the "master branch /docs folder" option and click the "Save" button:
   

We are done! After a few minutes (usually takes 2-5 minutes for the contents to be published the first time, afterwards updates are nearly instantaneous), you will find your new website's content under http://<github-username>.github.io/<github-repo-name>. In our example, the URL is https://zzamboni.github.io/test-ghost-blog/:

The workflow

After the initial setup, you need to follow these steps when you want to update your website:

1. Start Ghost inside your GitHub repository:

   npm start
   

2. Connect to http://localhost:2368/ and update your contents. You can also change the blog settings, themes, etc.

3. Re-crawl the site to generate the local copy:

   wget -r -nH -P docs -E -T 2 -np -k http://localhost:2368/
   

4. Update and push the whole git repository:

   git add .
   git commit -m 'Website update'
   

Steps 3 and 4 can be easily automated. I keep the following update_website.sh script in the repository with the name :

#!/bin/bash
OUTDIR=docs
LOCAL_GHOST="http://localhost:2368/"
wget -r -nH -P $OUTDIR -E -T 2 -np -k $LOCAL_GHOST && \
git add . && \
git ci -m 'Update website' &&  \
git push

Then you can just run this script from within your repository after making any changes:

./update_website.sh

Variations

The method described above is my favorite because it allows me to keep the source data and generated pages in the same repository. However, there are other variations that you might want to use:

• If your repository is named <username>.github.io, you cannot configure GitHub Pages to serve content from the /docs directory, it is automatically served from the root directory of the master branch. In this case you need to store only the generated pages in the repository (you could also reverse the setup: have the generated website in the root directory, and the local Ghost install under the /source directory).

• You can choose to serve contents from the gh-pages branch instead of the /docs directory. This allows you to keep the source and output still in the same repository. You will need to switch from one branch to the other between updating the contents and generating the static web site (you may need to keep both branches in different directories, so that your local Ghost install can still access its database in the master branch while you fetch it to generate the static website).

You can read more about the different ways to serve GitHub Pages content in the GitHub documentation.

And of course, you can use the same method to host your static content somewhere other than GitHub pages.

Security considerations

One of the most-touted benefits of a static website (also known, I discovered recently, as the JAMstack) is security -- without server-side active components, it's much harder for a website to be compromised.

Sharp-eyed readers may have noticed that with the setup described above, Ghost's entire database file gets checked into your repository. This file contains not only your published blog posts, but also your user definitions (including hashed versions of the user passwords) and draft posts.

The local Ghost install uses a SQLite database, stored at content/data/ghost-dev.db, which you can query using the sqlite3 command. For example, to see the user definitions:

sqlite3 content/data/ghost-dev.db 'select * from users'

While this seems scandalous, keep in mind that the active Ghost installation is only running locally on your machine, and is not accessible to anyone from the outside, even when it is running (the server is only bound to localhost). Still, you may want to keep in mind:

• Your name and email address are accessible. Your name is visible in any posts you write, but you may want to set your email address to one you don't mind being public.
• Don't use a password that you also use in any other place (this is a good security recommendation in general). The password is hashed, but this prevents the password from being useful even if someone manages to figure it out.
• If you share your machine with others, keep in mind that any other local users will be able to access your local Ghost install as long as it's running. If you don't trust those users, make sure you set a good password and shut it down when you are not using it.
• If you are really worried, add content/data/ghost-dev.db to your .gitignore file so it does not get checked into the repository. Make sure you make a backup of it separately so you can recover your blog in case of local data loss.

Conclusion

I followed the steps described above to create a test Ghost install, which you are accessing now, and its corresponding GitHub repository at https://github.com/zzamboni/test-ghost-blog/. You can also find this article published in my blog.

I hope you've found it useful. If you have any comments, please post them at the main copy of this article.

Hey! Welcome to Ghost, it's great to have you :)

We know that first impressions are important, so we've populated your new site with some initial Getting Started posts that will help you get familiar with everything in no time. This is the first one!

There are a few things that you should know up-front:

1. Ghost is designed for ambitious, professional publishers who want to actively build a business around their content. That's who it works best for. If you're using Ghost for some other purpose, that's fine too - but it might not be the best choice for you.

2. The entire platform can be modified and customized to suit your needs, which is very powerful, but doing so does require some knowledge of code. Ghost is not necessarily a good platform for beginners or people who just want a simple personal blog.

3. For the best experience we recommend downloading the Ghost Desktop App for your computer, which is the best way to access your Ghost site on a desktop device.

Ghost is made by an independent non-profit organisation called the Ghost Foundation. We are 100% self funded by revenue from our Ghost(Pro) service, and every penny we make is re-invested into funding further development of free, open source technology for modern journalism.

The main thing you'll want to read about next is probably: the Ghost editor.

Once you're done reading, you can simply delete the default Ghost user from your team to remove all of these introductory posts!

Ghost uses a language called Markdown to format text.

When you go to edit a post and see special characters and colours intertwined between the words, those are Markdown shortcuts which tell Ghost what to do with the words in your document. The biggest benefit of Markdown is that you can quickly apply formatting as you type, without needing to pause.

At the bottom of the editor, you'll find a toolbar with basic formatting options to help you get started as easily as possible. You'll also notice that there's a ? icon, which contains more advanced shortcuts.

For now, though, let's run you through some of the basics. You'll want to make sure you're editing this post in order to see all the Markdown we've used.

Formatting text

The most common shortcuts are of course, bold text, italic text, and hyperlinks. These generally make up the bulk of any document. You can type the characters out, but you can also use keyboard shortcuts.

• CMD/Ctrl + B for Bold
• CMD/Ctrl + I for Italic
• CMD/Ctrl + K for a Link
• CMD/Ctrl + H for a Heading (Press multiple times for h2/h3/h4/etc)

With just a couple of extra characters here and there, you're well on your way to creating a beautifully formatted story.

Inserting images

Images in Markdown look just the same as links, except they're prefixed with an exclamation mark, like this:

![Image description](/path/to/image.jpg)

Most Markdown editors don't make you type this out, though. In Ghost you can click on the image icon in the toolbar at the bottom of the editor, or you can just click and drag an image from your desktop directly into the editor. Both will upload the image for you and generate the appropriate Markdown.

Important Note: Ghost does not currently have automatic image resizing, so it's always a good idea to make sure your images aren't gigantic files before uploading them to Ghost.

Making lists

Lists in HTML are a formatting nightmare, but in Markdown they become an absolute breeze with just a couple of characters and a bit of smart automation. For numbered lists, just write out the numbers. For bullet lists, just use * or - or +. Like this:

1. Crack the eggs over a bowl
2. Whisk them together
3. Make an omelette

or

• Remember to buy milk
• Feed the cat
• Come up with idea for next story

Adding quotes

When you want to pull out a particularly good excerpt in the middle of a piece, you can use > at the beginning of a paragraph to turn it into a Blockquote. You might've seen this formatting before in email clients.

A well placed quote guides a reader through a story, helping them to understand the most important points being made

All themes handles blockquotes slightly differently. Sometimes they'll look better kept shorter, while other times you can quote fairly hefty amounts of text and get away with it. Generally, the safest option is to use blockquotes sparingly.

Dividing things up

If you're writing a piece in parts and you just feel like you need to divide a couple of sections distinctly from each other, a horizontal rule might be just what you need. Dropping --- on a new line will create a sleek divider, anywhere you want it.

This should get you going with the vast majority of what you need to do in the editor, but if you're still curious about more advanced tips then check out the Advanced Markdown Guide - or if you'd rather learn about how Ghost taxononomies work, we've got a overview of how to use Ghost tags.

Ghost has a single, powerful organisational taxonomy, called tags.

It doesn't matter whether you want to call them categories, tags, boxes, or anything else. You can think of Ghost tags a lot like Gmail labels. By tagging posts with one or more keyword, you can organise articles into buckets of related content.

Basic tagging

When you write a post, you can assign tags to help differentiate between categories of content. For example, you might tag some posts with News and other posts with Cycling, which would create two distinct categories of content listed on /tag/news/ and /tag/cycling/, respectively.

If you tag a post with both News and Cycling - then it appears in both sections.

Tag archives are like dedicated home-pages for each category of content that you have. They have their own pages, their own RSS feeds, and can support their own cover images and meta data.

The primary tag

Inside the Ghost editor, you can drag and drop tags into a specific order. The first tag in the list is always given the most importance, and some themes will only display the primary tag (the first tag in the list) by default. So you can add the most important tag which you want to show up in your theme, but also add a bunch of related tags which are less important.

News, Cycling, Bart Stevens, Extreme Sports

In this example, News is the primary tag which will be displayed by the theme, but the post will also still receive all the other tags, and show up in their respective archives.

Private tags

Sometimes you may want to assign a post a specific tag, but you don't necessarily want that tag appearing in the theme or creating an archive page. In Ghost, hashtags are private and can be used for special styling.

For example, if you sometimes publish posts with video content - you might want your theme to adapt and get rid of the sidebar for these posts, to give more space for an embedded video to fill the screen. In this case, you could use private tags to tell your theme what to do.

News, Cycling, #video

Here, the theme would assign the post publicly displayed tags of News, and Cycling - but it would also keep a private record of the post being tagged with #video.

In your theme, you could then look for private tags conditionally and give them special formatting:

{{#post}}
    {{#has tag="#video"}}
        ...markup for a nice big video post layout...
    {{else}}
        ...regular markup for a post...
    {{/has}}
{{/post}}

You can find documentation for theme development techniques like this and many more over on Ghost's extensive theme documentation.

Ghost has a number of different user roles for your team

Authors

The base user level in Ghost is an author. Authors can write posts, edit their own posts, and publish their own posts. Authors are trusted users. If you don't trust users to be allowed to publish their own posts, you shouldn't invite them to Ghost admin.

Editors

Editors are the 2nd user level in Ghost. Editors can do everything that an Author can do, but they can also edit and publish the posts of others - as well as their own. Editors can also invite new authors to the site.

Administrators

The top user level in Ghost is Administrator. Again, administrators can do everything that Authors and Editors can do, but they can also edit all site settings and data, not just content. Additionally, administrators have full access to invite, manage or remove any other user of the site.

The Owner

There is only ever one owner of a Ghost site. The owner is a special user which has all the same permissions as an Administrator, but with two exceptions: The Owner can never be deleted. And in some circumstances the owner will have access to additional special settings if applicable — for example, billing details, if using Ghost(Pro).

It's a good idea to ask all of your users to fill out their user profiles, including bio and social links. These will populate rich structured data for posts and generally create more opportunities for themes to fully populate their design.

Sometimes you might want to put your site behind closed doors

If you've got a publication that you don't want the world to see yet because it's not ready to launch, you can hide your Ghost site behind a simple shared pass-phrase.

You can toggle this preference on at the bottom of Ghost's General Settings

Ghost will give you a short, randomly generated pass-phrase which you can share with anyone who needs access to the site while you're working on it. While this setting is enabled, all search engine optimisation features will be switched off to help keep the site off the radar.

Do remember though, this is not secure authentication. You shouldn't rely on this feature for protecting important private data. It's just a simple, shared pass-phrase for very basic privacy.

There are lots of powerful things you can do with the Ghost editor

If you've gotten pretty comfortable with all the basics of writing in Ghost, then you may enjoy some more advanced tips about the types of things you can do with Markdown!

As with the last post about the editor, you'll want to be actually editing this post as you read it so that you can see all the Markdown code we're using.

Special formatting

As well as bold and italics, you can also use some other special formatting in Markdown when the need arises, for example:

• strike through
• highlight
• *escaped characters*

Writing code blocks

There are two types of code elements which can be inserted in Markdown, the first is inline, and the other is block. Inline code is formatted by wrapping any word or words in back-ticks, like this. Larger snippets of code can be displayed across multiple lines using triple back ticks:

.my-link {
    text-decoration: underline;
}

If you want to get really fancy, you can even add syntax highlighting using Prism.js.

Full bleed images

One neat trick which you can use in Markdown to distinguish between different types of images is to add a #hash value to the end of the source URL, and then target images containing the hash with special styling. For example:

which is styled with...

img[src$="#full"] {
    max-width: 100vw;
}

This creates full-bleed images in the Casper theme, which stretch beyond their usual boundaries right up to the edge of the window. Every theme handles these types of things slightly differently, but it's a great trick to play with if you want to have a variety of image sizes and styles.

Reference lists

The quick brown fox, jumped over the lazy dog.

Another way to insert links in markdown is using reference lists. You might want to use this style of linking to cite reference material in a Wikipedia-style. All of the links are listed at the end of the document, so you can maintain full separation between content and its source or reference.

Creating footnotes

The quick brown fox^[1] jumped over the lazy dog^[2].

Footnotes are a great way to add additional contextual details when appropriate. Ghost will automatically add footnote content to the very end of your post.

Full HTML

Perhaps the best part of Markdown is that you're never limited to just Markdown. You can write HTML directly in the Ghost editor and it will just work as HTML usually does. No limits! Here's a standard YouTube embed code as an example:

Creating a totally custom design for your publication

Ghost comes with a beautiful default theme called Casper, which is designed to be a clean, readable publication layout and can be easily adapted for most purposes. However, Ghost can also be completely themed to suit your needs. Rather than just giving you a few basic settings which act as a poor proxy for code, we just let you write code.

There are a huge range of both free and premium pre-built themes which you can get from the Ghost Theme Marketplace, or you can simply create your own from scratch.

Anyone can write a completely custom Ghost theme, with just some solid knowledge of HTML and CSS

Ghost themes are written with a templating language called handlebars, which has a bunch of dynamic helpers to insert your data into template files. Like {{author.name}}, for example, outputs the name of the current author.

The best way to learn how to write your own Ghost theme is to have a look at the source code for Casper, which is heavily commented and should give you a sense of how everything fits together.

• default.hbs is the main template file, all contexts will load inside this file unless specifically told to use a different template.
• post.hbs is the file used in the context of viewing a post.
• index.hbs is the file used in the context of viewing the home page.
• and so on

We've got full and extensive theme documentation which outlines every template file, context and helper that you can use.

If you want to chat with other people making Ghost themes to get any advice or help, there's also a #themes channel in our public Slack community which we always recommend joining!