# Structure of themes and theme components

**URL:** https://meta.discourse.org/t/structure-of-themes-and-theme-components/60848
**Category:** Developer Guides
**Tags:** reference, theme-guides
**Created:** [April 12, 2017, 3:41pm UTC](https://meta.discourse.org/t/structure-of-themes-and-theme-components/60848 "2017-04-12T15:41:30Z")
**Posts on this page:** 1
**Page:** 1

<div class="post-metadata">

### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [April 12, 2017, 3:41pm UTC](https://meta.discourse.org/t/structure-of-themes-and-theme-components/60848/1 "2017-04-12T15:41:30Z")

</div>

Discourse supports [native themes](https://meta.discourse.org/t/native-theme-support/47494/26) that can be sourced from a `.tar.gz` archive or from a remote git repository including [private repositories](https://meta.discourse.org/t/how-to-source-a-theme-from-a-private-git-repository/82584).

 ![56](https://global.discourse-cdn.com/meta/original/4X/1/c/b/1cb8db919e91f31c0192da0e184e0347ce72e3cb.png)

An example theme is at: [GitHub - discourse/discourse-simple-theme: Sam's simple discourse theme · GitHub](https://github.com/SamSaffron/discourse-simple-theme)

 ![32](https://global.discourse-cdn.com/meta/original/4X/5/b/a/5ba96345dc4a568292efa92d8cd49a22e9252e04.png)

The git repository will be checked for updates ([once a day](https://github.com/discourse/discourse/blob/main/app/jobs/scheduled/check_out_of_date_themes.rb)), 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](https://global.discourse-cdn.com/meta/original/4X/d/f/2/df244e03cd63d63608bf045b4cd9f00bcedb5b87.png)

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

```plaintext
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}.gjs
javascripts/{anything}.hbs

assets/{asset_filename}

settings.yml

```

Any of these files ⬆ 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.

> [@Split up theme SCSS into multiple files](https://meta.discourse.org/t/splitting-up-theme-scss-into-multiple-files/115126):
>
> Themes and theme components are becoming steadily more powerful, and developers are getting more and more ambitious. To make things easier for developers, themes can now split their SCSS into multiple files. [https://github.com/discourse/discourse/commit/268d4d4c828a0d9e3ca6b0b5b623db85eb32b9f3](https://github.com/discourse/discourse/commit/268d4d4c828a0d9e3ca6b0b5b623db85eb32b9f3) When creating a new theme with the [theme CLI](https://meta.discourse.org/t/beginners-guide-to-using-theme-creator-and-theme-cli-to-start-building-a-discourse-theme/108444), or sharing a theme [on github](https://meta.discourse.org/t/structure-of-themes-and-theme-components/60848), simply create a new folder called scss. Fill it with your .scss files, following any folder structure, and all the files will b…

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 below, and you can see more information about it at [https://meta.discourse.org/t/adding-metadata-to-a-theme/119205:](https://meta.discourse.org/t/adding-metadata-to-a-theme/119205:)

```json
{
  "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 Color Scheme": {
      "primary": "222222"
    }
  },
  "screenshots": ["screenshots/light.jpeg", "screenshots/dark.jpeg"]
}

```

Instructions on how to add settings to your theme available here: [Add settings to your Discourse theme](https://meta.discourse.org/t/how-to-add-settings-to-your-discourse-theme/82557).

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 tag.

ℹ See also:

- [Developing Discourse Themes & Theme Components](https://meta.discourse.org/t/developer-s-guide-to-discourse-themes/93648)
- [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)
- [Include assets (e.g. images, fonts) in themes and components](https://meta.discourse.org/t/include-images-and-fonts-in-themes/62459?source_topic_id=60848)

* * *

_Last Reviewed by @SaraDev on 2022-08-15T21:00:00Z_

* * *

This document is version controlled - suggest changes [on github](https://github.com/discourse/discourse/blob/main/docs/developer-guides/docs/05-themes-components/06-theme-structure.md).