Install the Discourse Theme CLI console app to help you build themes

[Discourse]

The Discourse Theme CLI is a ruby gem that allows you to use your editor of choice when developing Discourse themes and theme components. As you save files the CLI will update the remote theme or component and changes to it will appear live!

Installing

To play with it, make sure you have Ruby 2.5 or up installed.

If you are on Windows, you have 2 options:

Option 1: Windows Subsystem for Linux.

Windows 10 has access to a full Linux environment, you can use it to install ruby simply with sudo apt-get install ruby, this will give you Ruby 2.3.

Options 2: Older Windows

Older versions of Windows have no access to WSL, you can easily install Ruby with Ruby Installer, go for the recommended version and default settings for the install.

Mac OS version 10.13.3 ship with Ruby 2.3 out of the box, nothing special is needed. If you are running an earlier version of Mac OS consider using rvm, rbenv or homebrew to install a recent ruby.

---

Once Ruby 2.2 or later is running, open a terminal or command shell and run:

gem install discourse_theme

Once installed, to learn more about it:

discourse_theme

Upgrading

gem update discourse_theme

Features

The CLI provides 3 main functions:

discourse_theme new

You can use it to quickly create a new theme with discourse_theme new YOUR_DIR_NAME

discourse_theme watch

You can use it to monitor a theme and synchronize with a discourse site (with live refresh) using discourse_theme watch YOUR_DIR_NAME

What this means is that you can use your own editor to edit you theme and site will magically update with the changes!

discourse_theme download

You can download an existing theme from Discourse using discourse_theme download YOUR_DIR_NAME. You will then be given the option to start “watching” straight away!

Credentials

You will need to generate an API Key. Go to the admin area and generate a key there.

• Select a “User Level” of Single User when generating the key, not All Users .
• Make sure to check Global Key or you will receive 403 forbidden errors.

Credentials are (optionally) stored at ~/.discourse_theme. API keys are stored per-site, and the URL/theme_id for each directory is also tracked. If you ever need to change your settings, just add --reset to any command and you will be prompted for all values again.

Testimonials

“This tool is truly a GEM!” @awole20
“This is very very good.” @awesomerobot
“It’s working And it’s pretty dosh garn cool. Nice!” @angus
“OMG. It’s unbelievable.” @pfaffman

---

This document is version controlled - suggest changes on github.

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

Check document

Perform check on document:

[riladant]

Uploads via Admin >> Customize >> Themes disappear after a watched theme is saved.

How do we include image assets in the theme so they don’t get wiped out after a save is done?

[Arkshine]

Hi, welcome!

You need to include the assets in your theme component directly.

At the root, you create an assets directory.
Then, you declare them in about.json

"assets": {
  "<your_identifier>": "assets/<your_asset_filename>",
}

You can see an example here GitHub - MeghnaAJ/discourse-christmas-decorations.

[Arkshine]

A quick heads-up for developers who are using this tool to generate theme components:
You are encouraged to upgrade it!

A recent PR made the discourse-theme-skeleton repo as the default template. It will give you the latest configuration files!

[carbonrich (Richard Hawkins)]

Thanks!

It would be great to add an Update section to the topic…

Is it a --reset or a rubygem update?

[david (David Taylor)]

Good idea! I’ve added a ‘upgrading’ section to the OP

gem update discourse_theme

[Heinenen]

To install the gem on WSL, I had to run both
sudo apt-get install ruby and sudo apt-get install ruby-dev.
Maybe that can be added to the installation instructions.

[tgxworld (Alan Tan)]

@sam

Windows 10 has access to a full Linux environment, you can use it to install ruby simply with sudo apt-get install ruby, this will give you Ruby 2.3.

If you do not install ruby-dev, do you get an error? It should not be necessary to install ruby-dev as ruby itself is sufficient.

[Heinenen]

I’m pretty sure that I got an error that told me to install ruby-dev, otherwise I wouldn’t have known the package existed.
But I cannot reproduce it by trying to reinstall. Maybe I did something weird the first time.

[tgxworld (Alan Tan)]

Hmm that is indeed odd. Feel free to let me know if you can reproduce the problem again.