> For the complete documentation index, see [llms.txt](https://www.one.thezero.club/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.one.thezero.club/guide/theme-extending.md).

# Theme extending

This allows you to adapt the theme to your project's requirements while still being able to update Zero One safely in the future.

Think of it as a WordPress child theme, but with much more flexibility and control.

### Why Use Theme Extending?

A common mistake is to edit files directly inside:

```
site/plugins/zero-one/
```

While this may seem convenient at first, any changes made inside the plugin can be lost during future updates.

With Theme Extending, your custom files live separately from the core theme, making updates much safer and easier.

#### Benefits

* Keep customizations separated from the theme core.
* Update Zero One without losing changes.
* Override only the files you need.
* Build project-specific functionality on top of Zero One.
* Keep your project cleaner and easier to maintain.

{% hint style="info" %}
**Zero One recommendation:** Never modify files inside the Zero One plugin directly unless you are contributing to the theme itself.
{% endhint %}

***

### How Theme Extending Works

Zero One checks whether a file exists inside your `site/theme` directory.

If a matching file is found, Zero One will use that file instead of the original plugin version.

For example:

```
site/theme/snippets/footer.php
```

will override:

```
site/plugins/zero-one/snippets/footer.php
```

The folder structure and filename must match exactly.

***

### Examples

#### Blueprint Override

```
site/theme/blueprints/site.yml
```

overrides

```
site/plugins/zero-one/blueprints/site.yml
```

#### Snippet Override

```
site/theme/snippets/header/navbar.php
```

overrides

```
site/plugins/zero-one/snippets/header/navbar.php
```

#### Template Override

```
site/theme/templates/article.php
```

overrides

```
site/plugins/zero-one/templates/article.php
```

#### Controller Override

```
site/theme/controllers/site.php
```

overrides

```
site/plugins/zero-one/controllers/site.php
```

The same principle applies throughout the entire theme.

***

### How to Create an Override

Creating an override is simple:

#### Step 1

Locate the file you want to customize inside:

```
site/plugins/zero-one/
```

#### Step 2

Copy that file to the equivalent location inside:

```
site/theme/
```

#### Step 3

Preserve the exact folder structure.

For example:

```
site/plugins/zero-one/snippets/footer.php
```

becomes:

```
site/theme/snippets/footer.php
```

#### Step 4

Modify your copied version.

Zero One will automatically use your customized file instead of the original.

***

### Real-World Examples

Theme Extending can be used to:

* Add custom fields to existing blueprints.
* Customize header or footer markup.
* Modify page templates.
* Extend controllers with project-specific logic.
* Add custom schema markup.
* Change navigation structures.
* Adjust image handling and blueprint restrictions.

Many of the customizations mentioned throughout this documentation rely on the Theme Extending system.

***

### Safe Updates

Because your customizations live outside the Zero One plugin directory, you can update the theme without worrying about overwriting project-specific work.

This separation between **theme core** and **project customization** is one of the recommended workflows when building websites with Zero One.

{% hint style="info" %}
Think of `site/plugins/zero-one` as the engine and `site/theme` as your customization layer. Keeping them separate makes upgrades far easier and significantly reduces maintenance headaches.
{% endhint %}