How do I add an external javascript file into discourse?

General
1

I have a javascript file that I would to add to discourse, but I am not sure how. Am I required to create a plugin to include a js file or can I include the file in the source code? Either way, I am not sure how to accomplish this.

2

Adding a custom JavaScript file to Discourse can be done in multiple ways. Creating a plugin is the most modular and maintainable method, but you can also add JavaScript through the admin panel without directly modifying the source code. Modifying the source code is not recommended, as it makes updates and maintenance more difficult.

Here’s how you can add JavaScript to Discourse:

1. Adding JavaScript via the Admin Panel (No Plugin Needed)

This method is suitable for small scripts or one-off customizations.

Steps:

  1. Log into Discourse as an Admin.
  2. Navigate to:
Admin > Customize > Themes
  1. Select the theme you want to customize (or create a new one).
  2. Click on Edit CSS/HTML for the theme.
  3. Under the </head> section, add your JavaScript directly within a <script> tag or link an external file using <script src="..."></script>.
  4. Click Save and Preview.

Example:

If you want to add inline JavaScript:

<script>
  console.log("Hello, Discourse!");
</script>

If you want to include an external JavaScript file:

<script src="https://example.com/my-custom-script.js"></script>

2. Adding JavaScript via a Plugin

For more robust or complex scripts, creating a plugin is the preferred approach.

Steps to Create a Plugin:

  1. Set Up the Plugin Directory
  • Create a new folder under /plugins in your Discourse installation:
mkdir /var/discourse/plugins/my-custom-js
  • Inside this folder, create a plugin.rb file.
  1. Edit plugin.rb Add the following code to include your JavaScript file:
# plugins/my-custom-js/plugin.rb
# frozen_string_literal: true

# Plugin metadata
PLUGIN_NAME ||= "my_custom_js"

after_initialize do
  # Hooks into the Discourse asset pipeline
  register_asset "javascripts/my_custom_script.js"
end
  1. Create the JavaScript File Inside the plugin folder, create a javascripts directory and add your JavaScript file:
mkdir /var/discourse/plugins/my-custom-js/javascripts
touch /var/discourse/plugins/my-custom-js/javascripts/my_custom_script.js

Add your JavaScript code to my_custom_script.js:

console.log("This is my custom Discourse JavaScript!");
  1. Restart Discourse After setting up the plugin, restart Discourse to load the changes:
cd /var/discourse
./launcher restart app

3. Directly Modifying the Source Code

Not Recommended: Direct modifications to the Discourse source code will be overwritten during updates. However, if you must, you can place your JavaScript file in the appropriate folder (e.g., /app/assets/javascripts) and include it in the asset pipeline. This requires working knowledge of Ruby on Rails.

Which Method Should You Choose?

  • Use Method 1 if you only need to add a simple script for a single theme.
  • Use Method 2 for reusable or complex scripts that need to persist across updates and be shared with others.
  • Avoid Method 3, as it can lead to maintenance headaches.

Let me know if you need help with any of the steps!