Customizing handlebars templates

I am new to discourse and have been exploring the many ways to add custom styling to my forums.

So far, I have realized that the Custom CSS/HTML feature is mainly for adding new components to discourse. I used this awesome tool to get started Discourse Theme CLI (console app to help you build themes).

In terms of customizing Discourse’s template code, modifying the .css classes works fine because it is cascading. However, I have reached the point of customization where I would like to modify the template HTML (not just the CSS). From what I understand, that requires me to modify the handlebars code. Essentially, I want to hide some functionality and modify/extend some of the existing functionality.

I have found 3 popular approaches to achieve this, and am looking for input as to which way is the ‘best practice’.

  1. Change a template using css/html
    This seems like the quickest technique, but I was concerned about one of the replies by @eviltrout
  1. Change a template using a plugin outlet
    Beginner's Guide to Creating Discourse Plugins - Part 1
    From my understanding, this technique requires a plugin to be developed and added to discourse. Within the plugin directory, you create the same file structure to the file you wish to overwrite in order to change the functionality.

  2. Change a template using the client side PluginAPI
    A new versioned API for client side plugins
    It seems this technique requires a script tag to be added to a theme HTML file. The script tag identifies the path to the handlebars file to be overwritten. By using the withPluginApi you can essentially do the same as making a plugin.

I am having a hard time understanding the differences between these 3 options.

  • Is one of them considered Discourse’s ‘best practice’
  • Is one of them more maintainable and resilient to changes made in Discourse?
  • What is the difference between overwriting using a plugin outlet and the pluginAPI? Is there a difference aside from their implementation? Do these two achieve the exact same thing?
  • Is one more performant than another?
  • How do you extend Discourse’s current handlebars file and add some of your own custom code?
  • How do you delete/remove some of Discourse’s functionality that you don’t want to show on the UI?

I realize that this might be a case where these 3 options achieve the same thing and I need to choose which is best for my implementation/system. But anything to help me understand these better is much appreciated! :slight_smile:


Here are some brief answers:

Plugin outlets are a far better way to extend things, they shouldn’t be broken by changes made to Discourse.

Overriding a template will “replace” it. Plugin outlets are simply points in the page that you can “insert” content into. If you want to add content, a plugin outlet might be enough. Overriding templates should always be a last resort.

No, I don’t think so

You can’t really “extend” the templates, only replace them. The “how to customise discourse templates” link you posted has an example, but plugin outlets would be better.

The easiest way is through CSS changes in a theme as you mentioned. You could have a look at this theme, which @joebuhlig uses to hide a number of discourse features:

Hope that helps a bit - if you can describe which bit of discourse you want to change then it will be easier for people to give more specific advice.


Thanks for the super quick reply!! :slight_smile: This has been super helpful!

But I have a few more questions now.

I was wondering more if the plugin outlet (Beginner's Guide to Creating Discourse Plugins - Part 1) and the pluginAPI (A new versioned API for client side plugins) do the same thing? Their implementation is different, as one is a plugin added to discourse and the other is part of the HTML/JS. Is one of these methods preferred? Cause you also mentioned that:

So does that mean that the pluginAPI isn’t as resilient to changes as the plugin outlets?

I was hoping not to use ‘display: none’. I was snooping through some sites that have customized Discourse and came across this one. Overwatch Forums
It looks really clean, but lots of the out-of-the-box functionality is removed from the UI. I don’t see any ‘display: none’ to remove the functionality. Could it be that Blizzard used the pluginAPI or plugin outlet to replace some of the handlebars files, and omitted some of the code?