Make CSS changes on Your Site

Want to make some CSS changes on your Discourse site but not sure where to start? You’ve come to the right place! :+1:

You only need to read this topic if you’re very new to CSS. If you already know how to write and add CSS to your Discourse site, then you will most likely not need to read this topic.

We’ll cover a few subjects.

We’ll start with a brief introduction of what CSS is and some terms that you need to know. We will then move on to how you can add CSS to your Discourse site. Finally, we’ll talk about the browser inspection tools and how you can use them to find the selectors for the element you wish to target.

What is CSS?

Let’s start with the name. CSS stands for Cascading Style Sheets.

For the purposes of this guide you only need to understand three concepts about CSS


here’s a very simple CSS rule

p {
 color: red;

The rule above contains three things you need to learn about.

a selector: p means we want to target all of our HTML <p></p> (paragraph) tags
a property: color is a CSS property that allows us to set the color:
a value: red is the desired color we want to set on our property.

the combination of a property and a value is called a declaration

MDN, 2020. CSS Declaration

So, now that you know what one rule with one declaration looks like, it will be easier for you to understand more complex structures like…

a rule with multiple declarations…

p {
 color: red;
 background: blue;

multiple rules targeting different elements …

p {
 color: red;

h1 {
 color: green;

a combination of multiple rules each containing multiple declarations

p {
 color: red;
 background: blue;
 font-size: 15px;

h1 {
 color: green;
 background: yellow;
 margin-bottom: 15px;

and so on.


If you recall, CSS stands for Cascading Style Sheets. Cascading here is a very important aspect of how CSS works. We don’t need to get technical. The only thing you need to understand is that whatever comes last applies. So for example if you have this CSS

p {
 color: red;

and you then add then add something like this to your stylesheet

p {
 color: green;

and you end up with something like this

p {
 color: red;

p {
 color: green;

then your <p> tags will be green since that came last in your stylesheet.

You might be tempted to ask “why would I do this anyway?” and that’s a valid question. The answer is that you wouldn’t, but it’s important to understand this because that’s how the CSS you add to your Discourse site will work.

Every element in Discourse already has styles added to it. When you modify those styles, you’re not actually changing the defaults, you’re simply overriding them via the cascade. This a great assurance that you don’t really need to worry about permanently breaking anything on your site. If something is wrong with your added CSS, simply delete it and you’ll be back to the defaults.


This is a fancy word that refers to the fact that some CSS rules can be more specific than other. In general, all you need to know about this is that rules that are more specific will override the cascade.

Ok, but what makes a rule more specific? It has more selectors.

For example If you have some HTML that looks like this


and this CSS

div p {
  color: green;

and then try to change the color on the <p> tag with something like this

div p {
  color: green;

p {
  color: red;

it won’t work and it will remain green.

Why is this important to know? Because sometimes In Discourse we use more specific selectors because we want the styles to only apply to a specific HTML structure.

What does this mean for you? It means that if you want to override some default CSS, then your selector needs to be as specific or more specific than what we use in Discourse.

Don’t be discouraged by this. We’ll go over how you can find the selectors you need later on in this guide. For now, if you understand that more specific rules override the cascade, then you’re good to go.

Where do I add my CSS?

Before we talk about writing CSS, we need to talk about where you would add it on your Discourse site.

We will use a theme component. Theme components allow you add many customisations on top of your existing theme.

You can add CSS to the existing theme by

  • making a new theme component
  • enabling the theme component on your default theme
  • adding your CSS to the theme component

Here’s how you can do that.

  1. Head to the Admin section on your site

  2. Click on the Customize tab

    You should now see something like this:

  3. Click on the Components tab, and click Install

  4. Click + Create New. Then name your theme component – you can give it a short name that describes what the customisation will do. Then click Create.

  5. If you want to add your customisations to all themes on your site, click ‘Add all themes’ under the setting ‘Include component on these themes’.

    Then click the check button :white_check_mark:

    (If you don’t want to add it to all themes, you can pick which themes to add it to in that setting.)

  6. Click on Edit CSS/HTML

    You would then see something like this

    This is where you would add your CSS. Once you’ve added some CSS, hit the save button and it will apply immediately

    Notice how that editor has three top tabs?

    These tabs allow you to choose which devices your changes will apply to. The Desktop tab will allow you to make changes that only apply to desktop devices. The Mobile tab allows you to make changes that will only apply to mobile devices. Any CSS you add to the Common tab will apply to both.

    You might have also noticed that there are other other subtabs beside the CSS tab but those are out of the scope for this topic since we only want to focus on CSS in this guide. If you want to read more about those, have a look here Beginner's guide to using Discourse Themes.

Please note that if you have other user-selectable themes then you’d want to add your theme components to those themes too. This is also covered in the beginners guide to themes that I linked above. So, be sure to give that a read if this applies to you.

So, now that we’ve covered some basics about CSS and you know where to add it, let’s move on to how to find the selectors you need with your browsers inspection tools.

How do I find which selectors to use?

Browser inspection tools

For the sake of simplicity, I will be using Chrome to demonstrate how you can find selectors, but if you happen to use another browser, then rest assured that the process is very similar.

Okay, let’s start with something simple. Here’s a screenshot of my homepage and the element that I want to change

let’s say that for some reason I want that text to be red. I’ll start with a quick video to demonstrate how easy it is to make that change. After that, I’ll break down the process.

Now that you’ve seen how simple it is to make changes to Discourse CSS, let’s break down what happened in the video above.

  1. I right clicked on the element that I wanted to change.

  2. I clicked on inspect

  3. this thing showed up

    It’s OK If you’re not familiar with what that is. This is the browser inspection tool. In Chrome, this is called DevTools. You can read more about it here if you’re interested but you don’t really need to if all you need is to make some simple CSS changes.

  4. because I clicked inspect on the element I want to change, DevTools automatically focused on it

  5. I clicked on the plus sign here to ask DevTool to generate a new style rule for me

    and it did. Here’s what it created.

    screenshot of automatically generated CSS rule

  6. I added the declarations that I want inside that rule

    Screenshot of the CSS we added in the auto generated rule

  7. It looked good, so I copied the whole rule and went to my theme and pasted it there and clicked save.

  8. my CSS change is now applied

My changes are not being applied

Make sure the theme component is enabled on your themes

In the theme component, check that it has been included on your main theme, and that the theme component is enabled:

Check the specificity of CSS rules

The process I described above will work most of the time; however, there are times when the automatically generated rule is not specific enough (remember that fancy word?)

Let’s try an example where this happens. Let’s say that I want to change the color of the topic title here to green.

I would go through the process described above and get this rule

a.fancy-title {


and then add my color declaration like so

a.fancy-title {
  color: green;

and find that it’s not working. Why is that?


In Discourse we use this selector to set the color on that element

#topic-title h1 a {


which is more specific than what I was trying to add. So of course my changes won’t be applied. What do I do in this case? Well. here’s another video and I will also explain the steps afterwards

  1. I inspected the element that I want to change

  2. I asked DevTools to generate a rule

  3. I made my change and it didn’t apply because of specificity

  4. I looked at the selector used in Discourse for this style

    screenshot of the selector used in Discourse

  5. I copied that selector instead of the one DevTools generated for me

  6. I saved my changes in my theme

  7. My changes are now applied


We’ve barely scratched the surface in this topic. CSS is a very, very broad subject and I intentionally chose not to get into too much details about specific properties or things of that nature.

The goal of this guide is to help you get a basic grasp of how to make simple CSS changes on your Discourse site. If you’re interested in learning more about CSS, I would recommend that you search on the internet and find a resource that works for you. A resource that I would highly recommend is MDN

Unfortunately, I will not be able to help with how-to-CSS specific questions in this topic. I would recommend that you ask those on other Discourse communities that are more focused on learning web development like

However, if your question relates to how to add CSS to Discourse or any particular aspect of how CSS works in Discourse, then please feel free to ask here


Could this be made a wiki? The info under the heading Where Do I Add My CSS? needs updating, because there is no more Edit CSS/HTML button if you installed an existing theme — which is likely now if someone chose a theme through the newer Setup Wizard. Now we just use theme components that will be added to existing themes.

I can update it once it’s made into a wiki.


Ok this is done now :+1:


A post was split to a new topic: Making “bg image” visible intead of the “gradient” being applied