# Customizing handlebars templates
**URL:** https://meta.discourse.org/t/customizing-handlebars-templates/84186
**Category:** Support
**Created:** [March 29, 2018, 11:23pm UTC](https://meta.discourse.org/t/customizing-handlebars-templates/84186 "2018-03-29T23:23:50Z")
**Posts on this page:** 5
**Page:** 1
### Author:  [@sarahann](https://meta.discourse.org/u/sarahann)
#### Post date: [March 29, 2018, 11:23pm UTC](https://meta.discourse.org/t/customizing-handlebars-templates/84186/1 "2018-03-29T23:23:50Z")
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 [Install the Discourse Theme CLI console app to help you build themes](https://meta.discourse.org/t/discourse-theme-cli-console-app-to-help-you-build-themes/82950).
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**
[https://meta.discourse.org/t/how-to-customize-discourse-templates/34813](https://meta.discourse.org/t/how-to-customize-discourse-templates/34813)
This seems like the quickest technique, but I was concerned about one of the replies by @eviltrout
> [@eviltrout](#):
>
> Overriding templates is always risky, as if we change the underlying template to add or change a feature you will not receive the change. We recommend using plugin outlets and CSS wherever possible. But if you must override a template you can!
1. **Change a template using a plugin outlet**
[Developing Discourse Plugins - Part 1 - Create a basic plugin](https://meta.discourse.org/t/beginners-guide-to-creating-discourse-plugins-part-1/30515)
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 versioned API for client side plugins](https://meta.discourse.org/t/a-new-versioned-api-for-client-side-plugins/40051)
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! 🙂
---
### Author:  [@david](https://meta.discourse.org/u/david)
#### Post date: [March 29, 2018, 11:41pm UTC](https://meta.discourse.org/t/customizing-handlebars-templates/84186/2 "2018-03-29T23:41:00Z")
Here are some brief answers:
> [@sarahann](#):
>
> Is one of them considered Discourse’s ‘best practice’
> Is one of them more maintainable and resilient to changes made in Discourse?
Plugin outlets are a far better way to extend things, they shouldn’t be broken by changes made to Discourse.
> [@sarahann](#):
>
> 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?
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.
> [@sarahann](#):
>
> Is one more performant than another?
No, I don’t think so
> [@sarahann](#):
>
> How do you extend Discourse’s current handlebars file and add some of your own custom code?
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.
> [@sarahann](#):
>
> How do you delete/remove some of Discourse’s functionality
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:
> [@Joe's Personal Discourse Theme](https://meta.discourse.org/t/joes-personal-discourse-theme/83342):
>
> Here’s what may be a new way to use Discourse. Though I’m sure I’m not the first to think of this, I haven’t seen any posts about it. I’ve started a new private instance of Discourse that is designed to be a notes app replacement. Think of Evernote or OneNote but it’s Discourse and for only a single person. It occurred to me that all of these notes apps have things like URLs per note, APIs for interacting with the notes, email in, and the ability to share notes with others. But those are all t…
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.
---
### Author:  [@sarahann](https://meta.discourse.org/u/sarahann)
#### Post date: [March 29, 2018, 11:56pm UTC](https://meta.discourse.org/t/customizing-handlebars-templates/84186/3 "2018-03-29T23:56:14Z")
Thanks for the super quick reply!! 🙂 This has been super helpful!
But I have a few more questions now.
> [@david](#):
>
> 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.
I was wondering more if the plugin outlet ([Developing Discourse Plugins - Part 1 - Create a basic plugin](https://meta.discourse.org/t/beginners-guide-to-creating-discourse-plugins-part-1/30515)) and the pluginAPI ([A versioned API for client side plugins](https://meta.discourse.org/t/a-new-versioned-api-for-client-side-plugins/40051)) 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:
> [@david](#):
>
> Plugin outlets are a far better way to extend things, they shouldn’t be broken by changes made to Discourse.
So does that mean that the pluginAPI isn’t as resilient to changes as the plugin outlets?
> [@david](#):
>
> 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:
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](https://us.forums.blizzard.com/en/overwatch)
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?
---
### Author:  [@system](https://meta.discourse.org/u/system)
#### Post date: [July 31, 2020, 8:26am UTC](https://meta.discourse.org/t/customizing-handlebars-templates/84186/4 "2020-07-31T08:26:27Z")
---
### Author:  [@j.jaffeux](https://meta.discourse.org/u/j.jaffeux)
#### Post date: [July 31, 2020, 9:36am UTC](https://meta.discourse.org/t/customizing-handlebars-templates/84186/5 "2020-07-31T09:36:22Z")