Adding server-side themes to a Mastodon (or glitch-soc) instance
2024-07-14
For a while now, wetdry.world (and the fork of Mastodon/glitch-soc it runs, Chuckya) has been using a custom theme by Freeplay called Mastodon Modern by default, which gives the web interface a bit of a different look. However, despite vanilla Mastodon including an option in the instance settings to apply custom CSS overrides globally, this feature is not used to provide the theme; rather, the theme is available alongside the vanilla look and users are able to switch between the two.
The steps to add a custom theme between vanilla Mastodon and glitch-soc are different due to the latter adopting a "flavor"/"skin" system rather than Mastodon's theme system. On this page, I'll provide steps to add extra themes to both.
Mastodon (vanilla)
Mastodon's default themes are located under app/javascript/styles. Start by creating a new file in this directory with a name like mytheme.scss. Inside of it, you'll want to add a few lines:
@import 'mastodon/variables';
@import 'application';
@import 'mytheme/style';
This will serve as a standard dark/"default" variant of your theme. If you want to add high-contrast/light variants, create two new files in the same directory with corresponding names (e.g. mytheme-contrast.scss and mytheme-light.scss) and copy the above imports into them as well. You'll need to change "mastodon" in the first line to the name of the color variant (contrast, mastodon-light) and add an extra line at the very bottom (replacing <variant> with the same variant name used on the top line):
@import '<variant>/diff';
Once you've done that, create a new directory in app/javascript/styles named mytheme (if you want to use a different name, just change all occurrences of "mytheme" in this guide). In this directory, create a new file named style.scss. This is where your theme SCSS will go; feel free to change whatever in there.
Next, open up config/themes.yml. Add a new line at the bottom and insert the following:
mytheme: styles/mytheme.scss
Like before, if you want to add any variants of the theme, you'll need to add a new line for each one here.
Now to add a proper display name for the theme. This is done in the locale files in config/locales; if you don't know any other languages besides English, feel free to just modify en.yml (this goes for other languages as well). Under the themes section, there should already be some existing entries. Add one in the same section:
mytheme: My Theme (Dark)
Once again, you'll need to add a new entry for each variant. Now just run the command to rebuild assets like you would with any other update, and you should be set:
$ RAILS_ENV=production bundle exec rails assets:precompile
glitch-soc
When adding themes to glitch-soc, you may need to effectively add them twice; once for the vanilla flavor, and again for the glitch flavor. Due to large style differences between the two, I wouldn't recommend adding the exact same styles for both.
Vanilla flavor
To add a new theme for the vanilla flavor, follow the steps described above for vanilla Mastodon; however, once you get to the part where you edit config/themes.yml, stop and come back here.
glitch-soc uses a different system for defining themes (or "skins" as it refers to them). Head into app/javascript/skins/vanilla and create new directories with the same names as your theme and its variants. Create two files inside those directories: common.scss and names.yml. Put the following into common.scss (replacing mytheme with the variant name as needed):
@import 'styles/mytheme';
Once you've done that, you'll need to set the display name in names.yml:
en:
skins:
vanilla:
mytheme: My Theme (dark)
To add more languages, copy/paste the block above into your file again and change en to your desired language code.
After that, just rebuild the assets like usual, and it should appear in the skins under "Flavours" -> "Vanilla Mastodon" in your preferences:
$ RAILS_ENV=production bundle exec rails assets:precompile
Glitch flavor
The steps for adding a skin to the Glitch flavor are similar to the steps for the Vanilla flavor, except that the names and paths are slightly different. Follow the steps for the Vanilla flavor above, but replace the app/javascript/styles path with app/javascript/flavours/glitch/styles and the app/javascript/skins/vanilla path with app/javascript/skins/glitch. Replace the @import 'application'; line in mytheme.scss (as well as its variants) with @import 'index';.
Some themes may include a separate SCSS file with fixes specifically for the Glitch flavor. In this case, put the SCSS file in the same directory as your theme's style.scss file and add an import for it in mytheme.scss right before your flavor diff import (or the last line of the file if it isn't there).
In your skin's common.scss file, you'll need to put this instead:
@import 'flavours/glitch/styles/mytheme';
In your skin's names.yml file, you'll need to replace vanilla with glitch. Once you've done all of that, just rebuild your assets like normal and the skins should appear under "Flavours" -> "Glitch Edition":
$ RAILS_ENV=production bundle exec rails assets:precompile
You're done!
You should now have some extra themes added on your instance that users can choose from! If you have any further questions or issues, feel free to message me at @esm@wetdry.world.
