What HTML can you customize?

As someone new to Discourse, I’m trying to understand what can be customized and how. I know there are different themes and theme components available, and I also understand that in theory I can edit html, css, and javascript if I go to admin -> customize -> Themes -> [click on selected theme] -> edit CSS/HTML.

I’m trying to get a hold on how to use the dashboard that appears when trying at “edit CSS/HTML”. It shows </head> Header After Header <body> Footer Embedded CSS.

Is there any guide with examples on how to actually edit the html? I understand that on meta there are suggestions, but as far as I can see they are mixed in across various topics across the forum.

As an example of something that is confusing to me: this post asks if you could change the column order, which is a fairly basic html change. But the response is, basically, no you cannot without getting into some deep overrides.

So I’m trying to sort out what I can do with that “edit CSS/HTML” to customize my forum.

Yes, have a look at Developer’s guide to Discourse Themes.


Thanks. I’d seen this, but shied away bc the focus seemed to be about creating a theme, not simply editing my single forum.

I do see there is some guidance there on how to use the “edit CSS/HTML” dashboard. But, to confirm, I can change the html / css / JS without creating a new theme, right?

And it’s also not clear where/how I can move components, not just add/remove them (for example, changing the column order so the users group appears as the left most column on the page).

1 Like


I would definitely suggest going through that guide as well, don’t let the Theme aspect of it turn you away, as it dives in to multiple aspects of customization you will find beneficial.

1 Like

The link provided by Simon explains everything, but it’s quite long to read.

Basically, if you want to edit Discourse HTML, this can be done several ways:

  1. Through some pre-defined HTML tabs in your theme or component : Header, After Header, </body>, Footer.
  2. By targeting a “free” HTML space (outlet) that you can fill with your own HTML This can be done via a <script> tag that you can add in the </head> tab.
    Here is an example of the available outlets in a topic view:
  3. By overriding an existing HTML template. Templates sometimes contain a lot of HTML code, and you’ll need to copy-paste all of it in order to do your modifications. This can also be done in a <script> tag added in your </head>

Creating a theme, a theme component or “simply editing my single forum”, is quite the same here actually. The three are more or less done the same way.

Yes, it depends what you wan to do exactly, but usually the right way is creating a new theme component and write the HTML/CSS in here.


Thanks for this good info. I can wrap my head around adding html to an open space, and also hiding existing html with CSS (ie, display: none on the relevant div class, which I assume I just find using the inspector).

But how would I override html, such as moving a component around? Would you have a brief example?

I’m partially quoting the link pasted by simon:

Quick example of filling an outlet with a big red square; Here the outlet is located above the post list in a topic view:

<script type="text/x-handlebars" data-template-name="/connectors/topic-above-post-stream/a-unique-name">
  <div style="height: 200px; width: 200px;background: red"></div>

Notice the data-template-name attribute.

Quick example of overriding the navigation bar template:

<script type="text/x-handlebars" data-template-name="components/navigation-bar">
    {{#each navItems as |navItem|}}
      {{navigation-item content=navItem filterMode=filterMode category=category}}
    <div style="background: red; padding: 10px; float: left;">I added this block in the navigation bar template</div>
    {{custom-html name="extraNavItem" tagName="li"}}
    {{!- this is done to avoid DIV in the UL, originally {{plugin-outlet name="extra-nav-item"}}
    {{#each connectors as |c|}}
      {{plugin-connector connector=c class=c.classNames tagName="li" args=(hash category=category filterMode=filterMode)}}

Again, notice the data-template-name attribute.

Here’s the list of templates: discourse/app/assets/javascripts/discourse/app/templates at master · discourse/discourse · GitHub

And a useful theme component that highlight all the outlets locations: Plugin outlet locations theme component


Ok. Now I’m starting to get it. This is really helpful.

1. Where does the: type="text/x-handlebars" data-template-name="/connectors/topic-above-post-stream/a-unique-name come from? (as in, how do I know what to fill in there)?

And with the code example you gave to override a template, I can start to see how it’s possible, because I can take the template code and move it around, delete it, add to it, etc.

2. So I get the template code from the github link you provided? If so, that make sense, but it seems tough to find the right code. For example, which is the template for the home page?

3. Then paste that relevant code into the “edit css/html” dashboard. But where, under the first option (</head>)? I assume so from your earlier answer but would be helpful to confirm.

Hopefully this can all be helpful to others too.

To find the name and location of an outlet, I think the best way is the plugin I linked above.

To find the template corresponding to the part of the page you want to edit… That’s a bit more tricky.
I don’t know an easy way. A similar plugin would be great.
Sometimes, I look in the page HTML to see some code (a CSS class for example) that I feel will be unique, and then I search across all the templates files. I have cloned the Discourse repo on my home computer and I search across all these files using Sublime Text, but I’m sure there are other, better ways to do that.
Sometimes I look at the code of existing theme components that modify the page locations I also want to customize.

Yes, it is tough, but I’m no expert and I guess there are more efficient ways to do this!


When you come from Wordpress or phpBB and are used to directly edit the templates files in that or this directory, Discourse may seem cryptic… :sweat_smile:

Thank you. When comparing to wordpress, though, at least in my view, a big plus is that Discourse uses Ruby and Javascript, instead of PHP.