Making customization easier

One of mastodon’s principle benefits, IMO, is that instances can customize their UI to fit their community better.

A lot of platforms (tumblr, wordpress, reddit, etc) allow people to apply custom CSS without having to directly edit their site’s source code. Typically this is done via some kind of formatted, editable textbox exposed to administrators.

I think it would be beneficial, and increase the diversity of mastodon instances a lot, if the custom.scss was exposed in a similar way that e.g. the /about/more page text is (although with a proper SCSS-aware editor, with at least syntax highlighting, would be nice).

The pipeline for this should, I think, be fairly straightforward – when an administrator commits a new style, all that needs to happen is a background task needs to call the scss compiler on the custom.scss and replace the site’s CSS assets, and then notify whatever serves those of the change so that it can flush its cached version. It may be desirable, though, to compile the custom.scss separately so that the whole CSS need not be recompiled/invalidated. This would be complicated if the $color variables remain in there, but that brings me to my other proposal.

It would be even easier for admins if the $color variables were exposed in the same UI, e.g. as color pickers. This way the custom.scss can be standalone (not have to import the rest of the application scss or vice versa) and admins can easily make changes without having to poke around in scss or guess at color values. It would also open up the possibility of providing a live preview, so admins can easily see how the modified colors would look on the site.

Finally, the ability to upload your own logo image from the UI would be nice as well. I, for one, find it tiring to scp the file to my server, copy it to the mastodon directory, recompile the assets, and restart the services just to test a change to my logo.


IIRC this should be taken care of fairly automagicly with Rail’s asset pipeline. I think the major work here would just be exposing an easy way to edit the CSS source through the webmin interface.

1 Like

Nice to see a proposal for customizations.

Still I’m not sure that customizations for styles should have such treats different from other sources. For example, my customization to replace boosts with blue rupees alters messages as well as styles.

I do not know platforms which allow to customize styles other than Wordpress, but I think it was built on HTML templates and administrators could override both of HTMLs and styles. However, in case of Mastodon, it is built with React and hard to deliver similar customization feature.

Currently, for a good customization of instances, we need to get a better overall css (it’s a bit messy right now especially with components.scss).

We also need to have a theming system OR a way to completely replace the front end without having to maintain a fork of Mastodon (see this topic: Proposal : Separate Mastodon in two : API server and frontend ).

With a great theming system, or custom frontend, we could easily imagine hooks to insert some customisation interface (whether it’s a textbox where you put css or a full form/webapp) and be able to provide great way to customise instances.

Localisation strings should also be part of the process, a lot of instances rename ‘toot’ or ‘boost’ and it should be easier than maintaining a translation file with upstream, managing conflict manually.

Let me add that I can think of 2 different customizations for admins and 2 for users.


  1. Be able to easily change the about and about/more pages, changing background and other assets.
  2. Be able to change the web app, starting with to be able to set a default theme (see below).

1 has currently more priority than 2. Maybe 2 is even not desired at all, cause of support reasons. Admins can always offer other web apps. Except setting a default theme for your instance (see below).


  1. Be able to set a predefined color theme. Like the 3 standard theme’s I mentioned in my toot, but also extra admin made themes.
  2. Be able to set colors manually and/or install user made themes.

These two (admins and users) are different groups, different request as far as I am concerned.

(FYI, but you don’t actually have to change the default messages—as long as your changing the localization files, you’re in the clear)


Beyond a potential 2-set color theme option (dark/light, light/dark), I don’t see that giving the end user of an instance a lot of presentation customization power is warranted. To my mind, the instance admin should set the presentational tone as much as instance topic scope, policies for interaction, etc. It’s all part of the vibe the instance admin wants to create. They are the producers of the show, if you will. If users don’t like it, they can go to a different instance.

So, at least for the time being, discussion on appearance customization would be more productive if it just focused on what admins can do.

I mentioned it elsewhere, I think, but Flarum, and open source forum system that competes with Discourse (this forum system) provides an “Appearance” panel in the admin-side for admins to use. The full suite of presentation options to override are:

  1. Colors: 2 colors of choice to theme frontend (works on links and backgrounds. (Two text boxes for adding hex colors.)
  2. Logo: Upload an image to be displayed in place of the forum title. (Button to start file upload.)
  3. Favicon: Upload an image to be displayed as the forum’s shortcut icon. (Button to start file upload.)
  4. Custom Header: Add HTML to be displayed at the very top of the page, above Flarum’s own header. (Button to open pop-over textarea box for adding nested HTML.)
  5. Custom Styles: Customize your forum’s appearance by adding your own LESS/CSS code to be applied on top of Flarum’s default styles. (Button to open pop-over textarea box for adding CSS override rules.)

Some of those things may not apply to Mastodon, exactly, but you get the idea of what they allow admins to easily change. #5 gives the most bang for the buck. Track down any element/selector in the DOM using inspector tools and hit with your own overriding rules. The editor box is no frills, you put in the overriding CSS rules in plain text format, and save.

You can’t change core HTML, however, without building an extension for the purpose. But I think that’s beyond what’s needed here for Mastodon anyway.

There are times when admins want to change a UI string in Flarum, but that is also hard-coded and can’t be done without an extension for the purpose. So that’s one thing that could be done easier in Masto, perhaps.

But, maybe the first step there is to improve Mastodon core strings/icons, if they are not clear enough. That might eliminate some desire to want to change those things out of box.

I am not a Masto admin (yet), but I can appreciate that the core CSS probably needs some improvement, as @Naouak was suggesting, as is often the case with open source software. I’ve griped about the current desktop layout overblowing my 13" screen at full-width. When I see that kind of thing, which is a snub to UX no matter how you try to defend it, I’m pretty sure there are improvements that can be done somewhere.

1 Like

That’s a deficiency in the customization provided by, not mastodon. It’s very easy to change Mastodon’s custom theme.