Include assets (e.g. images, fonts) in themes and components

[Discourse]

Themes and theme components allow you to handle uploaded assets such as images and fonts. You can control what assets your theme accepts using the site setting: theme authorized extensions

Including assets in themes and components

For remote themes

Remote themes include:

• Themes and components installed from the Popular list of themes
• Themes and components installed using the From a git repository method

To upload assets to a remote theme or theme component, see Create and share a font theme component for a detailed example.

Uploading assets to local themes and components

Local themes include:

• The default Light and Dark themes that ship with every Discourse instance
• Themes and components created using the + Create New installation method
• Themes and components that were uploaded from your local computer using the From your device installation method.

To upload assets to a local theme or theme component, navigate to your theme or component and select + Add in the Uploads section:

In the Add Upload modal, choose a file and enter a SCSS variable name to use with with your CSS, javascript, and/or handlbars customizations

Once uploaded, the asset will pop up in the Uploads list:

Important Note: Do not add uploads to themes and components through the admin interface if the component was installed remotely from a git repository. Updates to the component will clear out any uploads that were not included in the git repository.

How to make use of the assets

SCSS

@font-face {
  font-family: Amazing;
  src: url($Comic-Sans) format('woff2')
}

body {
    font-family: Amazing;
    font-size: 15px;
} 

.d-header {
    background-image: url($texture);
}

When using ttf or otf fonts, be sure to use a format of opentype.

Javascript

<script type="text/discourse-plugin" version="0.8">
   console.log(settings.theme_uploads.balloons)
</script>

Handlebars

<script type="text/x-handlebars" data-template-name="/connectors/topic-above-post-stream/foobar">
  <img src="{{theme-setting "theme_uploads.balloons"}}">
</script>

HTML

You can’t directly add a theme asset to vanilla HTML (like in the header or after header sections of the customize admin panel). You have to use a handlebars template or the plugin API (more about those in Beginner's guide to developing Discourse Themes).

One workaround is to load your asset as a background image using SCSS (like the example above). So in the header section of your theme you might add:

<div class="my-custom-div">
  <a href="/"></a>
</div>

and then in your CSS:

.my-custom-div a {
    height: 50px;
    width: 100px; 
    background-image: url($asset-name);
}

Accessing theme uploads as settings

You may also treat theme_uploads as settings in JavaScript (related commit).

This allows themes and components access to theme assets.

Inside theme js you can now get the URL for an asset with:

settings.theme_uploads.name

And then you can do:

handlebars: {{theme-setting "theme_uploads.balloons"}}

javascript: settings.theme_uploads.balloons

Additional Information

• Create and share a font theme component

---

Last Reviewed by @SaraDev on 2022-06-10T20:00:00Z

---

This document is version controlled - suggest changes on github.

Last edited by @JammyDodger 2024-05-26T12:25:19Z

Check document

Perform check on document:

[bitmage (Brandon Mason)]

I have created an assets directory with 5 svg files for social media icons. I added them all to about.json as indicated by Create and Share a font theme component. I use them in my CSS in body_tag.html.

Expected: The icons should load.

Actual: The icons don’t display. The dev toolbar shows the browser has some concept of these existing as registered Images… but there’s no data in them.

What am I missing? Is there a build step or something?