Start a conversation

Theme Editing

Ghost comes pre-installed with the active theme Casper, which is designed to be a clean, readable publication theme that can easily be adapted for most purposes. However, Ghost can also be completed themed to suit your needs. 

Ghost theme documentation can be found here if you’re planning to work from scratch, or need a point of reference to make more advanced changes to the look of your publication. You can also browse our Marketplace, which is filled with a large selection of both free and premium pre-built themes - all of which can be edited.

To make customizations to your publication’s theme we’ve provided a basic theme editing guide below, however you will need some solid knowledge of HTML and CSS.

Getting Started

Before setting out to make your theme modifications, if you're only planning to make a quick font change, adjustment to color or you simply need to add additional scripts to your publication, you can always use the built-in code injection feature. Code injection can be used to inject code or styles into the site "publication-wide," or even on individual posts or pages using the code injection feature within the post settings menu.

For more advance customizations such as changes to the layout, preparing your theme for Ghost 1.0, or manipulating the display of content, follow the theme editing guide below to get setup.

Tip: When working with themes, we highly recommend following the install guide here and getting Ghost setup locally, that way you can work directly on your theme in a development environment.

Step 1: Download your active theme

The first step to editing your theme files would be to download a copy of your publication’s active theme. You can do this by following the steps below:

  1. Log in to your publication at
  2. Go to Settings > Design from the admin menu
  3. Locate the "Active" label from the list of themes and click Download

Step 2: Unzip your theme

Ghost themes are downloaded and uploaded as a .zip file. Before you are able to make customizations to your theme, you will need to extract the theme zip to a location on your computer for editing. 

Once extracted, you can edit your theme files directly from a text editor, or an HTML editor. There are several HTML editors available for download, however we recommend Brackets, a free, open source HTML editor that is available for both Macs and PCs alike. You can grab a copy of Brackets here.

With Brackets installed and open, follow the steps below to open your theme files:

  1. Click on File from the top menu
  2. Select Open Folder
  3. Choose the folder location where you extracted your theme

Note: If you are working from a local version of Ghost on your computer, you can find your theme folder within the /content/themes/ directory of your Ghost install, at /content/themes/theme-name.

Step 3: Making edits to your theme

Once the theme folder is open in Brackets, you will have access to all of the files that makeup your theme. 

You can make changes to any files within your theme, however important files to note are:

  • 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.
  • package.json is the file that contains the name of your theme, version information, and other configurable options such as the posts_per_page limit.

With the exception of the default.hbs file, the only required files for a theme are the index.hbs, post.hbs and package.json files. You can read more about individual template files and Ghost theme file structure here.

Note: If you are developing with Casper, please follow the instructions here before making changes.

Step 4: Packaging your theme for upload

Once you’ve made changes to your theme's template files, you will want to save all your work, then zip the entire folder containing the theme. Once saved, and zipped, the theme can be uploaded to your publication.

Developing with Casper

If you are making modifications to the Casper theme, please note that Casper styles are compiled using Gulp/PostCSS to polyfill future CSS. You'll need to make sure Node and Gulp are installed globally before beginning. After you’ve installed both, you’ll need to run the following commands from the Casper theme's root directory, e.g. /content/themes/casper:

$ yarn install 
$ yarn dev

Once installed, you can then make edits to the /assets/css/ files, which will be compiled to /assets/built/ automatically.

When you’ve completed making changes to Casper, the zip Gulp task packages the theme files into dist/<theme-name>.zip, which you can then upload to your site.

$ yarn zip

If you host your site on Ghost(Pro) and have questions about working with your theme, please reach us directly by email for help.

Choose files or drag and drop files
Was this article helpful?
  1. Sarah Frantz

  2. Posted
  3. Updated