A beginner’s guide: How to customize your new Discourse forum with CSS (Part 1)

This is a comprehensive guide split into several parts, about CSS customization in Discourse forums. It is intended for non-coders and non-technical people.


This guide is for anyone (like me!) who is customizing a Discourse community from scratch. I know that the CSS can be a little overwhelming at first if you don’t know your way around it. Luckily it’s relatively simple once you start trying it out for yourself.

All the information in this guide is taken from the Arrowhead forums. I do not pretend to be an expert, so more advanced coders may find more efficient ways of coding. I’m open to feedback and suggestions for improvement!┬áSpecial thanks to Arrowhead, the staff at Discourse and the Discourse community.




1. First make a new theme and name it appropriately

Customize -> Themes -> New Theme

All CSS in this guide is under one new theme named “Arrowhead” and is set to default. I have kept the premade “Light” and “Dark” theme and make it selectable to users in case they prefer those (or if something goes wrong with the custom theme!).

2. The Colour Scheme

Customize -> Theme -> Your Custom Theme -> Edit Colour Scheme -> New Colour Scheme

Like your new theme, make a new colour scheme and name it appropriately. Play around with the colours, see what works best for you and looks good for your brand.

There’s not much to say here since it’s personal preference, but on the Arrowhead forums we’ve tried to stick to our brand’s four main colours for continuity.

Remember to select this new colour scheme in your custom theme using the drop down menu.

3. Uploads

Customize -> Theme -> Your Custom Theme -> Uploads

Here you can upload any assets you refer to in your CSS. In this case I’ve uploaded different custom fonts which I’ve used.

You can also upload assets in the site asset thread located in the Staff area of the forum.



4. Your forums must be responsive: Common, Desktop or Mobile?

Customize -> Theme -> Your Custom Theme -> Edit CSS

This means that your forum scales to fit the size of your browser window or mobile devices for optimum viewing.

In Discourse you have the option of inserting CSS in three categories: Common, Desktop or Mobile.

Anything you put under Common will affect both Desktop and Mobile. Desktop is just for changes you want to be made on the desktop, and Mobile is only for changes made to mobile.

Since Discourse provides a great out-of-the-box setup for mobile, I have not made any major additions or changes to it. All the CSS in this guide is inserted in Common or Desktop.

5. Sections of your forums: CSS, Header, Body or Footer?

Customize -> Theme -> Your Custom Theme -> Edit CSS

The different sections here refer to different parts of the forums. In order to make the changes in particular places, you need to know where to enter the CSS or code.

I will clearly state which part my code goes into.

6. CSS notes

Customize -> Theme -> Your Custom Theme -> Edit CSS

In all of my code I use notes to remind me what each part does. It’s a lot easier to see everything when you go back after a break, or if someone else needs to see your code.

To make notes you simply use /* at the beginning of your note and end with */. In all my code snippets below you can edit any of my descriptions to better suit your needs.


Now we’ve covered the very basics, see part 2 for all the code.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.