Page asset management

There are three ways of managing page assets, such as images. We’ll go through each method briefly. If you have questions about any method please reply to this topic. If you think there is an issue with a page asset management method please submit a bug report by clicking “Bug Report” in the header.

Direct Links

You can just link to an asset hosted elsewhere. If you just need to include some images in your page, this is probably the easiest and best way of doing it. For example, we load some of the lottie animations in our landing pages directly from a digitalocean space.

Theme Assets

If you include an asset in a theme, and set that theme as landing page’s theme using the “theme” page attribute, the asset will be loaded when the page is loaded and be available as normal in other files in the theme. Note that theme asset variables cannot be used directly in page files.

One way of using theme assets in your pages is by using CSS classes with a background-image attribute. This is how the image assets in Pavilion’s Landing Page Header are loaded. The classes used in the header html have relevant rules in the Pavilion Landing Theme which use image assets included in that theme.

See here in the Pavilion Landing Theme and check out the markup of our header

Page Assets

You can also load an asset in the landing pages plugin itself. This method is useful if you need to use an asset directly in your html.erb markup. However, we recommend you only use this method as a fallback, if direct links or theme assets are not suitable.

First, add your asset(s) to your pages repository, preferably in a dedicated assets folder. Then, create a file called assets.json, which is where you’ll register your assets. You can put put this file anywhere in your pages repository. Your assets.json should have one attribute, a register, containing a hash with asset names as keys and the path of the asset relative to the pages repository root as the value. Check out Pavilion’s assets.json for an example.

Once you’ve added and registered your assets, you need to specifically include them in a page so that they’ll be loaded for that page. The only way to do this currently is by using the assets attribute in a page.json file. For example, we can see that the assets/welcome.json file, which is registered as the welcome asset is included on Pavilion’s “Welcome” page in that page’s page.json file

Once your pages repository with your

  1. asset;
  2. asset registry; and
  3. page that includes an asset

is imported into your discourse, whenever the page that includes the asset is loaded the asset will be available as an instance variable in the page body.html.erb. The instance variable will be in the form


For example


You can see Pavilion’s welcome.json animation is used in our “Welcome” page via its @welcome instance variable in two places:

This results in the lottie animation for the title of our “Welcome” page.