# Edit theme

The theme uses a modern development stack to compile and optimize styles and scripts.

For advanced customization, it is recommended that you are familiar with using the command line and code editors such as [Visual Studio Code](https://code.visualstudio.com/) or [Cursor](https://www.cursor.com/). A compatible version of [Node.js](https://nodejs.org/) is also required to manage project dependencies.

### Stack Overview

The theme is built using the following tools:

* [**Gulp**](https://gulpjs.com/) - Task runner for automating build processes *(used in Ghost’s official themes)*
* [**Tailwind CSS**](https://tailwindcss.com/) - Utility-first CSS framework used for styling.
* [**BrowserSync**](https://browsersync.io/) - Enables live reload and multi-device testing.
* [**GScan**](https://github.com/TryGhost/gscan) - Ghost’s theme validator.

You can use either **npm** or **yarn** to install and manage dependencies.

### Available Commands

{% tabs %}
{% tab title="npm" %}

```bash
npm install    # Install theme dependencies
npm run dev    # Starts development mode with live reload
npm run test   # Runs gscan to check for compatibility issues
npm run zip    # Builds a .zip file of the theme
```

{% endtab %}
{% endtabs %}

### Development Mode

When running in development mode, two URLs will be generated:

* `http://localhost:3000` – Local preview.
* `http://<your-ip>:3000` – For multi-device testing on the same network.

These preview URLs **proxy your local Ghost site**, which must be running in the background.

Use your Ghost site URL (e.g., `http://localhost:2368/ghost`) to access the admin panel.

### Custom Theming

The theme uses a variable-based theming system defined in the `assets/css/pina.css` file. This approach allows it to manage fonts, color palettes, and dark mode behavior using CSS custom properties.

By centralizing these values, it becomes easier to:

* Create and adjust **color schemes.**
* Maintain consistent styling across light and dark modes.
* Extend the theme with new design options.

This system improves flexibility while keeping the codebase clean and easy to maintain.

### Custom Components

The theme includes a set of **custom Tailwind-based utilities** defined in the `assets/css/utilities.css` file.

These utilities are used throughout the theme to ensure **consistency** and to simplify the development of more **advanced and flexible features**.

They include:

* **Containers** - for layout structure.
* **Layout helpers** - such as wrappers, spacers, and grid utilities.
* **Headings** - with preset spacing and font styles.
* **Buttons** - with consistent appearance across the site.

This setup allows for faster iteration and easier maintenance when building new functionality into the theme.

### Custom Cards

**Breeze** uses **custom Tailwind styles** and **local JavaScript** to improve the appearance and performance of Ghost cards.

This ensures visual consistency across all devices and removes the need for external scripts.

### Custom CSS

The following steps are for adding custom CSS only. If you need to change existing styles or modify layout components, edit the corresponding `.hbs` templates directly  this is the standard approach when using Tailwind CSS.

Follow the steps below to add your own custom styles:

{% stepper %}
{% step %}
**Create the Custom File**

* Create a new file in `assets/css/` example: `custom.css`
  {% endstep %}

{% step %}
**Add Your CSS**

* Write your styles inside the `custom.css` file that was created.

```css
/* Example */
.custom-button {
    background-color: #000;
    color: #fff;
    padding-block: 0.5rem;
    padding-inline: 1rem;
    border-radius: 0.5rem;
}
```

{% endstep %}

{% step %}
**Import the File**

* At the end of  `assets/css/tailwind.css` import your custom file.
  {% endstep %}
  {% endstepper %}

This ensures your styles are included in the final build and take advantage of Tailwind’s optimization.

### Simple Edits (No Build Required)

For small changes such as:

* [Translate](/docs/breeze/advanced/translate.md)
* [Posts per page](/docs/breeze/advanced/posts-per-page.md)

You don’t need to install dependencies or run Ghost locally. These can be done by directly editing the theme files.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pinathemes.gitbook.io/docs/breeze/advanced/edit-theme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.