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.

Extension hooks (no build required)

Essence provides two files for quick customizations that survive a rebuild of compiled assets:

• assets/custom.css — custom styles, loaded after theme CSS
• assets/custom.js — custom scripts, loaded after theme JS

Edit these directly in the downloaded theme zip. No npm run build step is needed for changes in these files alone.

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

Essence uses a Rollup build pipeline to compile CSS, JavaScript, and vendor assets:

• /assets/custom.css and /assets/custom.js: Edit directly, no build needed.
• /assets/css/, /assets/js/: Source files that require building.
• /assets/built/: Compiled output after npm run build.
• /assets/vendors/: PVS and other bundled vendor scripts (copied during build).

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/css/ or /assets/js/.
2. Run npm run dev for live rebuilding during development.
3. Test changes in your browser.
4. When done, run npm run build for production assets before zipping.

Third-party licenses

Essence WebGL shader presets include code derived from React Bits. Attribution and license terms are documented in THIRD_PARTY_LICENSES.md at the theme root (MIT + Commons Clause).

Review this file before redistributing modified shader code or derivative themes.

Common Customizations

Custom CSS

• For small tweaks, add to assets/custom.css (no build needed).
• For advanced changes, edit source CSS in /assets/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 in /assets/js/ and build.
• Test to avoid conflicts with PVS (init-pvs.js) and Essence effects.

Disabling built-in features

Examples that require source edits + rebuild:

• Page intro: default.hbs inline script and assets/js/page-intro.js

Testing Your Changes

• Check your site on various devices and browsers.
• Confirm all Ghost features work.
• Test navigation, pagination, shader backgrounds, and liquid glass fallbacks.

Reverting Changes

If needed:

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