How to develop custom themes


(Sam Saffron) #1

Discourse now supports native themes that can be sourced from a remote git repository.

An example theme is at: GitHub - SamSaffron/discourse-simple-theme: Sam's simple discourse theme

To create a theme you need to follow a specific file structure. These are the files you may include:

about.json (required)





The about.json file structure is:

  "name": "The name of your theme",
  "about_url": "",
  "license_url": "",
   "assets": {
       "font": "assets/some_font.woff2"
   "color_schemes": {
       "Scheme Name": {
          "primary": "AAABBB"

Instructions on how to add settings to your theme available here: How to add settings to your Discourse theme.

The file structure matches the theme custom CSS / HTML.

At the moment there is still no way to provide optional color schemes

Further reading

Check out the other articles with the #themes tag.

:warning: See also: Discourse Theme CLI (console app to help you build themes)

How to add settings to your Discourse theme
Allow users to select dark / light theme
How to create and share a color scheme
Alien Night Theme - A free Dark Theme for Discourse
About the theme category
Custom user fields show on Activity, but not Summary page
Adding Unsolved button to top menu using custom HTML
Color Scheme Contest (with Prizes!)
Some basic questions about discourse and rails
Add support for theme settings
How to modify the header HTML, but still remaining the default founctions
How to modify Login/Register Modal
Push to digital ocean from command line and rebuild
Compact member list
Discourse deployment using github or bitbucket?
A more robust ecosystem for creating, sharing and modifying themes
Do you have original customisations?
Timefuser Theme
How to add settings to your Discourse theme
Custom assets upload folder?
Allowing users to control video play speed
How to remove sticky top bar?
Create and share a font theme component
Beginner's guide to using Discourse themes
Battle Axe - A free theme by the hockey community
(Joshua Rosenfeld) #2

@sam, does this currently, and/or are there future plans for this work to affect existing sites customizations? As someone who did a significant amount of CSS work on my site, do I need to do anything to ensure my work is safe in the future?

(Sam Saffron) #3

Themes are an evolution of site customizations we automatically migrate all the structures.

(Christoph) #4

If I remember the previous setup correctly, there was an option for “common” and one “mobile”, now there is “common”, “desktop” and “mobile” and the previous “common” has become “desktop”, right? Does that imply any changes in how the customization works? (I’m probably wrong, but just wondering…)

Edit: Hm, there does seem to be some difference: previously, when I would reload the an /admin page, my top navigation bar would simply disappear. Now I get white space instead.


I haven’t tested it as of yet so apologies if I’m missing something but will there also be an option for exporting the files from discourse or will it be the case of having to copy/paste out of discourse into github

(Sam Saffron) #6

Import export from a dcstyle file still exists just like it did before.


I’m new (just 2 days) using discourse and I’m starting to work on a custom theme, but I have a doubt with the structure of this.

In the .html should I include the templates from this directory?

I’ve previously worked with Handlebars, but I’m not sure about this.


(David Taylor) #8

As I understand it, themes are not designed to override handlebars templates. Themes can supply additional CSS and HTML to use on top of the standard templates. The only files you can have in a theme are listed in the top post.

The best thing to do if you’re just getting started is go to /admin/customize on your forum and play with the theme options there. Then once you’re happy think about exporting it to GitHub so others can use it.

If you want to do more fancy things like override templates you probably want to look into making a plugin.


Is there a way to use the “Assets for the site design” topic for that?

(Joshua Rosenfeld) #10

Locally? Yes. You can upload an image there and link to it in your local theme. The issue is the inability to share that asset when you publish your theme for others.


I mean, if your theme comes as a git repository, you can have an assets/ folder with the images, and then the system could use that to upload all this to the “Assets for the site design” topic, replacing the references to assets/foo.png in the JSON with the relevant URL in the posts.

(Joshua Rosenfeld) #12

So Sam said (emphasis mine):

Theis will be supported, it just isn’t yet.


I was suggesting a way…

(Joshua Rosenfeld) #14

My apologies…I thought you were asking how to do this now…


No worries :slight_smile:

I’m curious what @sam has in mind, as this topic is not the only option, and could use some automation love.

(David Taylor) #16

This has already been implemented, I guess the OP of this topic needs to be updated

(Sam Saffron) #17

crap I need to update that, it actually works…

(Angus McLeod) #18

After porting the Header Search Plugin to the theme format, I have some notes that others developing themes may find useful

  1. This topic about the use of the plugin api in site customizations applies equally to themes.

  2. Shortened method definitions don’t work. Change any method(){} to method: function(){}.

One other note while I’m at it. When importing a theme from the web, if the repo url is incorrect there should probably be an error message in the modal (e.g. “Repository not found”).

Edit. One other thought. Now that the Header Search Plugin exists as both a theme and a plugin, my initial thought was to still use the same repo as the Header Search Plugin. I don’t want to get rid of the plugin format, as that has advantages over the theme format if you’re using multiple themes and plugins.

However there doesn’t seem to be any way to use the same repo for both formats. If you just stick both plugin and theme files into the same repo, you get a server error when trying to import the theme.

(Sam Saffron) #19

Will fix that error message, agree it is far from ideal.

Hmm, this should work cause ES6 is transpiled. Going to need to see a broken example.

I am not following this, a theme component can belong to multiple themes, that is exactly how the hamburger theme selector lives on every theme on meta.

What disadvantages do you think themes have for end consumers? Cause I would much prefer to address that then figure out a parity format.

(Angus McLeod) #20

Specifically, shortened method definitions don’t seem to work for methods with attached ember observers.

For example, if you shorten the initSizeWatcher method declaration in the head_tag.html file in the Header Search theme, you’ll get

SyntaxError: unknown: Unexpected token, expected , (33:3)

EDIT: ah nvm, this is also the case with JS in a plugin. I just haven’t noticed it before :slight_smile:

Yeah sorry for the somewhat vague comment.

The only generally applicable issue (from my limited understanding of themes) is that you can’t add settings and translations with a theme component. The Header Search Plugin has a setting - override_extra_info: "Show the search box in the header instead of the topic title when scrolling on a topic" - which I removed for the theme. There is a decent possibility the Header Search feature would benefit from other settings and translations.

Somewhat more vaguely, I have the sense that there are probably more limitations with themes that will arise if I try to extend the Header Search feature functionality in the future. Adding more and more JS to the Head in this fashion doesn’t feel very future proof. Maybe this feeling is unjustified.

If theme components are the way to go for functionality like header search (which shouldn’t really be the subject of ‘user choice’), it may help to have a setting that lets you automatically include a component in all themes; i.e. a ‘default / universal component’ setting.

Screenshot at Aug 14 10-07-41

What I actually had in mind with the reference to ‘advantages’ when using multiple themes and plugins was something quite specific to me. I have 25 different plugins at once on one instance (and will have more in the future). Keeping them all as plugins, rather than a mixture of plugins and themes makes them easier to manage, for example a number of my plugins share CSS classes so I have a ‘global plugin CSS’ approach I’m trying to cultivate. Also, I’m finding it convenient to share custom frontend libraries I’ve written between plugins themselves, which is easier to manage if everything is a plugin.

cc @tophee (re your question in another topic)