Changing PieFed’s appearance with themes

As of today, PieFed includes a ‘theme engine’ which makes it easier for people with low or no Python skills to change how PieFed looks and behaves.

Let’s start with the app/templates/themes directory in the PieFed codebase. In this directory there will be a sub-directory for each theme that is available. As of this writing there is only one, called ‘high_contrast’. If you want to make a new theme, copy the high_contrast directory and rename the copy to something 20 characters or less. Let’s pretend your theme is called ‘my_theme’.

Inside ‘high_contrast’ is high_contrast.json. This file contains a bit of information about the theme, to improve the user experience of choosing which theme to enable. Currently the only information in there is a user-friendly name for our theme but I might add more in future. In our new theme we to rename high_contrast.json to be the same as the directory containing it, or ‘my_theme.json’ in this case. Also change the user friendly name in the JSON to something like “My Theme”. Take care not to change the double quotes.

Also in the theme directory are two files: styles.css and scripts.js. You can remove the high_contrast CSS and put your own. high_contrast’s scripts.js is empty and is just a placeholder to encourage you to add your own JavaScript.

In PieFed on the main menu, go to Account -> Settings and check if your new theme is shown as an option in the Theme field. If not then you messed up the naming of the theme directory or theme.json file. The theme setting here will change the theme you use while browsing PieFed – to change it for everyone go to Admin -> Misc Settings and set the ‘Default theme’ option.

Editing styles.css and scripts.js will probably be enough for most people. But in addition to that you can copy any .html file from app/templates into your theme and that copy will be used instead of the default one. For example, the home page template is app/templates/index.html so if you copied it to app/templates/themes/my_theme/index.html then any edits you make to the copy will be used to render the home page in a different way than the stock PieFed theme would!

If you want to theme a template in a sub-directory, like app/templates/post/post.html then the correct place for your copy will be app/templates/themes/my_theme/post/post.html.

The .html templates are a mixture of HTML and a language similar to Python called Jinja2.

I very much look forward to seeing what people come up with!

Licensing

PieFed is licensed under the open source AGPL license and themes are considered derivative works. As a result, themes need to be licensed under the AGPL as well.

This means that anyone who distributes or shares their PieFed themes must do so under the terms of the AGPL, ensuring that the source code of the theme remains open and accessible to others. If you do not distribute or share the theme with others then you do not need to share the source code with the public.

Using the theme to serve a publicly-accessible PieFed instance is “distribution” so you need to be able to make the theme source code available to everyone, either as a downloadable file or a git repository. If you choose to send PieFed a PR of your theme it will be gratefully accepted.