Structure of themes and theme components

Discourse now supports native themes that can be sourced from a remote git repository, or from a .tar.gz archive. Recently we also added support for branches and private repositories.

An example theme is at: GitHub - discourse/discourse-simple-theme: Sam's simple discourse theme

The git repository will be checked for updates (once a day), or by using the Check for Updates button. When changes are detected the Check for Updates button will change to the Update to Latest.

image

To create a theme you need to follow a specific file structure. These are the files you may include:

about.json (required)

common/common.scss
common/header.html
common/after_header.html
common/footer.html
common/head_tag.html
common/body_tag.html
common/embedded.scss

desktop/desktop.scss
desktop/header.html
desktop/after_header.html
desktop/footer.html
desktop/head_tag.html
desktop/body_tag.html

mobile/mobile.scss
mobile/header.html
mobile/after_header.html
mobile/footer.html
mobile/head_tag.html
mobile/body_tag.html

locales/en.yml
locales/{locale}.yml

stylesheets/{anything}/{anything}/{anything}.scss

javascripts/{anything}.js
javascripts/{anything}.hbs
javascripts/{anything}.hbr

assets/{asset_filename}

settings.yml

Any of these files :arrow_up: are optional, so you only need to create the ones you need.

For those looking to split theme SCSS into multiple files, that’s now possible.

For those looking to split up theme into multiple JS files, just add the JS files you want into the javascripts directory.

The about.json file structure is:

{
  "name": "My Theme",
  "component": false,
  "license_url": null,
  "about_url": null,
  "authors": null,
  "theme_version": null,
  "minimum_discourse_version": null, 
  "maximum_discourse_version": null,
  "assets": {
    "variable-name": "assets/my-asset.jpg"
  },
  "color_schemes": {
    "My Colour Scheme": {
      "primary": "222222",
    }
  }
}

Instructions on how to add settings to your theme available here: How to add settings to your Discourse theme.

To tell Discourse that you are going to add a theme component and not a full theme just add the line "component": true to the about.json file

The file structure matches the theme custom CSS / HTML.

Further reading

Check out the other articles with the #themes tag.

:information_source: See also:


Last Reviewed by @AlexDev on 2022-08-15T21:00:00Z

58 Likes

Hi Sam. Does Discourse offer a non-coding UI for easy theme creation (didn’t find an entry for this)? Or do we have to write codes for these CSS files?

Hope to make my own theme while I can’t write codes.

Hey Sherran,

Recommend you start with Beginner's guide to using Discourse Themes

1 Like

Thanks Joshua. I just read the post and the guide is helpful. I learned how to set color themes and install theme components offered by mods.

While I am wondering if I can even customize a component? Because the component, like the brand header, does not have an option to change the background color and it just can’t fit my page.

So I can use GitHub resources to install new features, while I can’t really make changes to have the features fit my page. Is that I do have to write codes like CSS or JSON? to make some changes?

Thanks.