Skip to Content
DocsAspectEditing Theme Code

Editing Theme Code

To customize your Ghost theme beyond the available settings, you’ll need to edit the theme files directly. This guide explains how to safely modify your theme’s code.

Before You Begin

Before editing your theme code, keep these important points in mind:

  • Make backups: Always back up your theme before making changes
  • Test changes: After modifications, thoroughly test your site on different devices
  • Theme updates: Custom changes may be lost when updating your theme
  • Code knowledge: Basic understanding of HTML, CSS, and Handlebars is helpful

Editing Theme Files

Follow these steps to edit your theme files:

  1. Download a copy of your theme from Ghost Admin:

    • Go to Settings → Theme
    • Click on the active theme’s dropdown menu
    • Select Download to get a ZIP file of your theme

  2. Unzip the theme archive to a folder on your computer

  3. Use a code editor of your choice (such as Visual Studio Code, Sublime Text, or Atom) to make the required changes

  4. Common files you might want to edit:

    • assets/custom.css for custom styles
    • assets/custom.js for custom scripts
    • .hbs files for template modifications (e.g., post.hbs, index.hbs, page.hbs)
    • default.hbs for changes that affect the entire site

  5. Once you have finished editing the code, you need to re-zip the theme directory:

    • On macOS, right-click on the theme folder and choose Compress from the context menu
    • On Windows, right-click on the theme folder, select Send to, and then choose Compressed (zipped) folder

  6. Upload the modified theme to your Ghost site:

    • Return to Settings → Theme
    • Click Upload theme and select your modified ZIP file
    • Activate the uploaded theme

Common Theme Customizations

Here are some common theme customizations you might want to make:

Modifying CSS Styles

To change colors, fonts, spacing, or other visual elements:

  1. Add custom styles in the assets/custom.css file
  2. Use browser developer tools to identify the elements you want to modify

Changing Templates

To modify how specific pages or posts are displayed:

  1. Find the relevant template file (e.g., post.hbs, page.hbs)
  2. Make your changes while preserving the Handlebars syntax ({{...}})
  3. Be careful not to remove essential Ghost functionality

Adding Custom Scripts

To add JavaScript functionality:

  1. Add custom scripts in the assets/custom.js file
  2. Test thoroughly to ensure they don’t conflict with existing functionality

Using Theme Partials

Many themes use partials (reusable code snippets) stored in the partials/ directory. Editing these files will affect all pages that use them.

Testing Your Changes

After making changes:

  1. Check your site on different devices and browsers
  2. Verify that all Ghost features still work correctly
  3. Test pagination, navigation, and special features

Reverting Changes

If something goes wrong:

  1. Return to Settings → Theme
  2. Upload your backup theme ZIP file
  3. Activate the original theme

By following these guidelines, you can safely customize your Ghost theme to meet your specific needs while maintaining its core functionality.

Updating ThemeGhost Config