Native theme support

At the moment Discourse supports 3 mechanisms for amending the “theme” of a Discourse instance:


Plugins can amend both backend and frontend code. They are the most advanced level of customisation.


  • Can change backend or frontend
  • Straightforward to distribute, live on Github


  • Tricky to install as it requires a container rebuild
  • High risk as it is allowed to amend backend code
  • Hard to isolate to a single site
  • In a multisite environment admin on master site must install to make available

Colors (via admin)


  • Trivial to change color scheme for current site
  • Isolated to one site, can be changed at will on any instance


  • No history / revisions
  • No preview
  • Only colors

Site Customization (via admin)


  • Trivial to change CSS/HTML
  • Isolated to one site, can be changed at will on any instance
  • Easy preview


  • CSS can not be split into many “files”
  • No history / revisions
  • No simple mechanism for sharing

Given that we are already considering shipping a material design theme and people have already done so many amazing themes I think it would be nice to have a built-in way to colleberate and theme Discourse.

The idea:

Easily distributable, safe, visual extensions to Discourse.

  • Themes all live in a well structured git repository (or filesystem)

  • Allow easily to add and remove themes (from github branch or filesystem) via the admin panel

  • Completely isolated, themes can be installed and removed from any site in a multisite install

  • Create a themes category on meta similar to plugins, have every Discourse install use that category as a browsable directory in the admin panel.

  • Themes have zero access to the backend code, can only amend frontend

  • Easy dev mode, where changing theme updates site right away

  • When a theme is updated remotely (on git) notify admin that a new version exists, allow them to preview change and update.

  • Themes are easily composable, you can enable 1 or many.



I like it. Having version control especially.

Would this replace or supplement the existing Customise pages? They have the advantage of being very quick to enable on a live site. Very useful for experimenting and bug fixing.

1 Like

In this scenario, the Customise pages should continue to work on top of the theme that is active, IMHO.


This is not a replacement to any of the existing systems, just an addition, a vehicle for theme authors to ship themes


Could you elaborate on this? I understand that different themes could target separate parts of the frontend, but does this imply the need for an ordering/cascading mechanism?

1 Like

Would be nice if you had the ability to have multiple themes active, and let the end user select the theme they want to use, some can use dark, while others can use a light theme, etc.

I guess, ordering and grouping is a challenge. But some stuff can wait for a v2.

I think that having “composable” themes is likely going to cause more headaches than it will solve – unless themes are forced to be really really simple. I foresee themes that use JavaScript to achieve certain effects, and we all know that there’s an awful lot of JS code out there that doesn’t play nicely with others. :slight_smile:

By “github” do you mean Git? Or will this be hitching Discourse’s theme support irrevocably to a specific Git provider? This could have ramifications for companies using Discourse who prefer to not host their theme publicly, or pay for private repositories on GitHub.

I’m not sure how it works under the hood at present in Discourse, but is it worth thinking about “full themes”, in which no out-of-the-box CSS/templates are loaded at all – only that of the theme? That would facilitate light-weight, super-fast themes…


Yeah that it a good point, v1 will not be composable, except that site customization will be able to apply to “all themes” or a “single theme”

Yeah any git source is fine.

1 Like

What do you think about allowing normal users to preview a theme by passing the theme URL as a query parameter?

That would allow sharing ideas before they are enabled by admin as the default.

Along the same lines, I’m wondering what other things could be done to allow non-admin designers to iterate more quickly to develop new themes.

I do want to get to allowing users to select themes and coupling a user account with a theme… But the ability to inject an external theme into a site by an end user is going to have to be a plugin to start off.


Great idea.

I’ve been working on an update to my material design theme and learning the front end API as I’m going along.

From this, thinking If all CSS classes within widgets were undateable at runtime, perhaps using the API widget settings mechanism added by @eviltrout below, it would open up extensive conditional formatting options.


I’d love to see that!

I’d consider this a disadvantage… :thinking:


True that :slight_smile:

A major disadvantage

I think proper versioning is just as important for themes as it would be for plugins.

Had any site been using a custom theme when we launched our new vertical sidebar, that update would have almost certainly broken their site. It was already a challenge for sites with basic HTML & CSS customisations. We also have to assume that some forums will be using themes that they themselves did not make, but rather a 3rd party did, as is the case for 99% of WordPress sites. Which means they’re at the mercy of a 3rd party should an update unexpectedly break their site.


Do we also want to support theme use cases like this one?


Great initiative! Here are a couple of areas I believe are important to make it easy to develop themes.

  1. Use a documented naming convention for CSS classes
  2. Fast development workflow to update themes
  3. Control and customization over Discourse features

Whether you go for SUIT CSS naming conventions or something else is a topic for another day, but with a documented naming convention people would find it easier to recognise classes, which to use and which to avoid. Avoiding ids in the default Discourse CSS would be nice as well as removing unused classes in the markup.

If it is possible to poll, pull themes via git and update themes automatically (or something smarter?) it would be really great. Also, is overwriting or extending handlebars templates something that is encouraged? If so, themes should have an easy way to do so.

If it’s possible to decide which Discourse features you want and not, it would be even easier to theme. For instance, some won’t want the new (and very useful) sidebar on topics or the sticky header . Instead of hacking these features away it would be nice with a checkbox to simply disable those features. We should also make sure that all colours in use actually have a corresponding setting in the color-section of the admin panel.


I am also interested in ways to have pre populated data. My example would be a shell for online courses, but a module of other guidance to get started is another.

How about a plugin that would pull in code to add to the current customize interface? It could pull from and add in themes that way. How hard would that be?

And then, how hard would it be to have a plugin that pulled in a set of topics that it would create, or update when a new version was available?

An ode to the Discourse 2013 theme

It’s been 3 years since Discourse went flat, and I still haven’t forgotten about the good old days when boxes and buttons had some meat on them:


See “A first look at Discourse” for a quick trip down memory lane.

I’m not saying it was objectively better, but I do miss it. Our current theme is ruthlessly functional - which makes perfect sense for a default, baseline theme - but it lacks personality.

These applications have personality:

I’m very excitedly looking forward to the day when we can reintroduce “Discourse 2013” as an alternative stock theme, alongside many others :heart_eyes:


Any update on this ?

Trying to migrate a community from phpbb to Discourse, all I can hear is “I want my dark theme” or “I want my light theme”

Haven’t found a plugin allowing to switch between two css/color :confused:

1 Like