The Ghost Themes Developer Hub

Welcome to the Ghost Themes developer hub. You'll find comprehensive guides and documentation to help you start working with Ghost Themes as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Package.json

Specifications for the package.json file

A good reference for your package.json, is always the latest Casper


Ghost's package.json is heavily based upon the npm package.json, and is fully compatible with npm. There is absolutely no requirement or expectation that your theme will be published to npm, however we recognise that it useful to utilise npm for managing theme dependencies.

If you're not sure about any aspect of this spec, you should refer back to the npm package.json docs for reference.

Package.json must be valid JSON

Remember to add double quotes around all of your property names and that every property except the last one should be separated by a comma.

Minimal Example

Below is a quick example of the minimum recommended information in package.json:

{
    "name": "your-theme-name",
    "description": "A brief explanation of your theme",
    "version": "0.5.0",
    "engines": {
        "ghost": ">=1.0.0"
    },
    "license": "MIT",
    "author": {
        "email": "yo[email protected]"
    },
    "config": {
        "posts_per_page": 10
    }
}

Required properties

name

All themes are required to have a package name. This tells us what you want your theme to be called, otherwise the only reference we have is the name of the zip file or folder that the theme is contained within, which is not controlled by the theme developer.

A valid name is:

  • Lowercase
  • URL-safe (that means no spaces, use hyphens)
  • Doesn't start with a dot or underscore
  • A maximum of 214 chars long

An example of a valid name is my-favourite-theme.

This should be lowercase and hyphenated, E.g. my-theme not My Theme.

How Ghost will use this:

The name of your theme will be used to list your theme. We may use a humanise function to display your package name, e.g. my-theme may be displayed as My Theme.

version

In order to manage updates, your theme is required to provide a semver-compliant version number.

You can find out more about semver on semver.org, or you can also install node-semver to check your version manually.

A semver version MUST include 3 parts: major.minor.patch.

Theme developers are expected to version their themes sensibly. The simplest rules are:

  • If the theme is available to be used, it should have at least reached version 1.0.0.
  • Change the 3rd patch number for bug fixes only
  • Change the 2nd minor number for feature additions
  • Change the 1st major number for breaking changes

author

Author should be an Object and your package.json must contain an author.email property. url and name are optional.

"author": {
    "name": "Theme Author",
    "email": "[email protected]",
    "url": "https://example.com"
}

The email is required so that themes which are distributed (either free or paid) have a method of contacting the author so that users are able to get support, but more importantly so that the Ghost team can reach out about breaking changes and security updates.

The package.json file is NOT accessible when uploaded to a blog so if the theme is only uploaded to a single blog, no one will see this email address.


Recommended Properties

config.posts_per_page

With Ghost 1.0 we removed the the "Posts per page" settings from the Ghost Admin and keep it to the current theme to control it. You can set it up in your package.json like this:

"config": {
    "posts_per_page": 3
}

If Ghost doesn't find this key in your themes' package.json it'll fall back to its default of 5 posts per page. This value is output in themes as part of the @config global variable.

description

Provide a short description of your theme and what makes it unique. This should be text-only (no HTML or markdown) and limited to 300 characters.

engines

Use engines.ghost to indicate what version of Ghost your theme is compatible with. This should be a valid semver version or version range that Ghost can use to understand if your theme can be installed.

Example for a theme, which is build for Ghost 1.0:

"engines": {
    "ghost": "^1.0.0"
}

license

A valid license string, as per npm package.json. We recommend MIT 😉


Optional Properties

gpm

GPM should be an Object as well. It takes a type property which indicates the nature of its purpose. For now, this will only be "theme".

The second property categories is an Array that should list out at most 2 Ghost Marketplace categories for inclusion. Categories can be found here but are subject to change.

Here's an example for a theme with "Minimal" and "Personal Blogs" categories:

"gpm": {
    "type": "theme",
    "categories": [
        "Minimal",
        "Personal Blogs"
    ]
}

screenshots

You can provide a relative path or absolute URL to both desktop & mobile screenshots, e. g.

"screenshots": {
    "desktop": "assets/screenshot-desktop.jpg",
    "mobile": "assets/screenshot-mobile.jpg"
}

demo

You can also provide a working demo page of your Ghost install which runs the current theme.

homepage

The homepage should be a valid URL (GitHub URL is ok).

Package.json

Specifications for the package.json file