Theme extending

One of the biggest advantages of Zero One is that you can customize virtually any part of the theme without modifying the original plugin files.

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.

Zero One recommendation: Never modify files inside the Zero One plugin directly unless you are contributing to the theme itself.

---

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.

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.