Theme overrides

Before we get into the 'How?' and 'Why?', we should familiarize ourselves with the basics about Publii's theme structure, as this will help us to more clearly see the benefits of overrides. If you've poked around your Publii website's files a bit (much easier to do with the website file location options that were added in the Publii Beta 3 release) then you might have seen that there are several file types that go into the creating a theme:

.hbs files - To make our app's themes easier to get to grips with they're built using Handlebars, which works alongside HTML to create the structure of a theme. This makes the theme code more understandable for newcomers without giving up flexibility for people with a bit more experience.
.css files - Handlebars gives us the structure, but it's CSS that gives us the style! CSS code is used to set the position of elements, give them color, shape and styling; all the stuff that gives a theme its character.
.js files - Javascript is the backbone of the more complex features you find on the modern web; if you're interacting with a website beyond filling out forms and clicking links, then Javascript is probably behind it.
.json files - JSON files are, basically, text files that are used to store data; they're used in Publii themes to store configuration settings, theme translations and the like.

You may run into a few more file types, but the ones covered above are by far the most common and essential. Now we know what kind of files are in the themes, we can take a look at just what overrides can do.

What are theme file overrides?

As we saw in the last section, each part of a given theme is controlled by a particular file type; so what happens if we want to make changes to the base style, or add some new elements to the structure? The logical answer here is that you can use the existing files; need to change the style? Open the correct CSS file, and add your changes. This method will work, but it won't take long until you run into a few issues.

The big one to worry about is updates; let's say you add your own code to one of the theme files; once an update to that theme is released, there's a good chance that the modified file will be replaced during the update process, rolling it back to the default and eliminating any changes you added before. Then there's the problem with tracking changes; with so many files making up a theme it can be easy to forget exactly which file has been modified with our own code; this problem gets even worse if multiple people are working on the project independently.

Overrides provide a solution to both of these problems, by allowing Publii users to create override files, which are essentially copies of the existing theme files that are stored separately, that will 'override', or replace, the original file. In a nutshell; when Publii creates the page layout using the theme files, it will check if there are any files in the override location, and will replace the existing theme files with these overrides.

By creating a separate location for the override files, it's possible track exactly which files have been modified, and keep a central, unchanging location for inserting your own code into a theme. And since the override folders are ignored by Publii except when building the website, you'll be able to keep your modifications backed up even during app updates. This way you can apply your own code to a theme without the risk of losing changes in updates, or struggling to keep track of which files have been changed.

How to use override files

Creating override files is simplicity itself; just follow these steps:

Locate your website's theme directory; this will be in the path specified in the Site Location option in your Publii Global Settings; by default this will be C:\Users\yourUserName\Documents\Publii\sites.
Inside this directory you'll see folders for each of your Publii websites; each website can have its own overrides, so open the folder for the site you wish to change. You'll see three folders; input, output and preview; the themes folder will be in the input folder, so open this, and finally, open the themes folder; this contains the themes currently installed for your chosen website.
Now we need to find the folder containing the theme we want to create an override for, and note the name of the theme's folder. Then, we'll need to create a new folder in the themes directory, but name it themeName-override; for example, if you wanted to modify the Simple theme, which is in a folder called simple, then you'd create a folder called simple-override in the theme directory of your input folder eg. Documents\Publii\sites\your-siteName\input\themes
```
- simple-override
  |- index.hbs
```
Now you're ready to start overriding files! You can override virtually any file from the theme simply by creating a copy in your new override directory; copy and paste the file from the original theme location into the override folder; if the original file was in a subfolder of the theme files, then the override copy should also be placed in a folder with the same name. For example, if we wanted to override the main.css file, which is in the themeName\assets\css folder, then we'd need to create an assets folder in our themeName-override directory, then create a css directory within that, and finally, create a copy of the main.css file in the css folder.
With that done, the copied file in the override directory will now be used by Publii to build the website instead of the original file, so you can start adding your own code to the file as needed. Remember that you only need to add files that you want to override into the override folder; if a particular file isn't found in the override folder then the original file will be used automatically.

Important points to remember

Overriding files is a very easy process as we saw in the last section, but there are some important things to bear in mind when using this feature:

If you want to override the language.json file it's advisable to use the languages directory, as this will merge the override file with the original file; details on how to do this can be found in our Publii Theme Translation Guide.
If you want to create an empty .hbs file in the directory, make sure that it contains at least one white space character; if the file is left completely empty then you'll receive an error when trying to create your website.
The overridden version of your theme won't appear in the list of themes in the basic settings, only the original version of the theme will be visible.
The name of the overridden theme can't be changed from the original, but you can modify the configuration options.
It is possible to add extra helpers via the helpers.js file if needed; this includes helpers that weren't in the original version of the theme.
The thumbnail.png file for the theme cannot currently be overridden, as it used only on the app settings screen where only files from the original theme directory are visible.
If you wish to insert additional files to the theme, put them in the assets directory.

With that in mind, you're now ready to go; have fun adding your own personal touches to the themes you find in Publii, and if you've got any questions about the guide above feel free to get in touch with us in the comments below!