Editing Theme Code

Essence

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)

The theme 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

The theme 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

The theme 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 the theme 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

Scope

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.

Key Files

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.

Thoughts

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

Feed

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

Moment

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

Aspect

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

OnFlow

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

Thesis

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

Format

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