Skip to Content
Save 20% on our Theme Bundle $199 instead of $249
DocsOnFlowEditing Theme Code

Editing Theme Code

To fully customize your Ghost theme, you may need to edit the theme files directly. This guide covers how to safely edit and build your theme code.

Before You Start

  • Backup: Always back up your theme before changes.
  • Test: After editing, test your site on different devices.
  • Updates: Custom changes may be lost after a theme update.
  • Skills: Basic HTML, CSS, and Handlebars knowledge is helpful.

Editing Theme Files

  1. Download your theme from Ghost Admin:
    • Go to Settings → Theme
    • Click the active theme’s dropdown and select Download
  2. Unzip the theme folder on your computer.
  3. Open the files in a code editor (e.g., VS Code, Sublime Text).
  4. Edit these common files:
    • assets/custom.css (custom styles, no build required)
    • assets/custom.js (custom scripts, no build required)
    • .hbs files (templates, e.g., post.hbs, index.hbs)
    • default.hbs (site-wide changes)
  5. When done, re-zip the theme folder:
    • macOS: Right-click > Compress
    • Windows: Right-click > Send to > Compressed (zipped) folder
  6. Upload the new zip to Ghost:
    • Go to Settings → Theme
    • Click Upload theme and select your zip
    • Activate your updated theme

Working with Source Files and Build Tools

Some themes use a build system to compile assets:

  • /assets/custom.css and /assets/custom.js: Edit directly, no build needed.
  • Other files in /assets/: Source files that require building.
  • /assets/built/: Compiled assets after running the build process.

Setting Up the Build Environment

  1. Install Node.js if you don’t have it.
  2. Open a terminal and navigate to your theme folder.
  3. Run npm install to install dependencies.

Build Commands

# Watch for changes (development)
npm run dev
 
# Build for production
npm run build
 
# Build for production, update translations, and create a zip
npm run build:prod
 
# Test the theme with GScan
npm run test

Editing Source Files

  1. Edit files in /assets/.
  2. Run npm run dev for live rebuilding.
  3. Test changes in your browser.
  4. When done, run npm run build for production assets.

Common Customizations

Custom CSS

  • For small tweaks, add to assets/custom.css (no build needed).
  • For advanced changes, edit source CSS and run the build process.
  • Use browser dev tools to identify elements.

Template Changes

  • Edit .hbs files for layout/content changes (e.g., post.hbs).
  • Keep Handlebars syntax ({{...}}) intact.
  • Avoid removing required Ghost code.

Adding JavaScript

  • For simple scripts, use assets/custom.js.
  • For advanced features, edit source JS and build.
  • Test to avoid conflicts.

Testing Your Changes

  • Check your site on various devices and browsers.
  • Confirm all Ghost features work.
  • Test navigation, pagination, and special features.

Reverting Changes

If needed:

  1. Go to Settings → Theme
  2. Upload your backup theme zip
  3. Activate your backup
Updating ThemeDeploying Theme