---
title: "Advanced Editing Theme Code"
description: "Learn how to edit theme files and build source assets to customize your Ghost theme's appearance and functionality."
url: "https://www.priority.vision/docs/guides/advanced-editing-theme-code"
scope: shared
appliesTo: [Essence, Scope, Thoughts, Feed, Moment, Aspect, OnFlow, Thesis, Format]
lastUpdated: 2026-09-18
---

# Editing Theme Code

<div className="theme-blocks">

### 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.

    For persistent customizations without re-editing the theme zip after every update, prefer [Code Injection](/docs/guides/custom-code-injection/) in Ghost admin.

## 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](https://nodejs.org/) 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

```bash
# 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](https://www.reactbits.dev/). 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](https://nodejs.org/) 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

```bash
# 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

| File | Description |
|------|-------------|
| `default.hbs` | Main layout template |
| `index.hbs` | Homepage template |
| `post.hbs` | Single post template |
| `page.hbs` | Page template |
| `landing.hbs` | Landing page template |
| `home.hbs` | Blog homepage (when using landing routes) |
| `tag.hbs` | Tag archive template |
| `author.hbs` | Author archive template |

## 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](https://nodejs.org/) 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

```bash
# 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](https://nodejs.org/) 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

```bash
# 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](https://nodejs.org/) 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

```bash
# 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](https://nodejs.org/) 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

```bash
# 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](https://nodejs.org/) 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

```bash
# 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](https://nodejs.org/) 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

```bash
# 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](https://nodejs.org/) 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

```bash
# 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

</div>

## Documentation Index
> Fetch the complete documentation index at: https://www.priority.vision/docs/llms.txt
> Use this file to discover all available pages before exploring further.