Scroll Sites
Scroll Sites
Breadcrumbs

Inject Custom JavaScript

Inject custom JavaScript (JS) into the your site to customize the help center theme beyond the options offered in the visual theme configurator UI.

This is an advanced feature for users that are comfortable with web development. Adding custom JS can break your site or affect it in unexpected ways.

We recommend you only use this feature if you’re experienced using JavaScript. Adding custom JavasScript can break your site or affect it in unexpected ways.

Please note, problems resulting from your custom code is not within the scope of product support.

Applying Custom JavaScript

You can inject custom JavaScript using the JavaScript code editor built into the theme configurator:

  1. Open the theme configurator from Site Settings > Look and feel > Customize theme.

  2. Click on the Code tab.

  3. Enter your custom JavaScript code in the JS editor field.

  4. Click Save changes once you are happy with your code.

Now you can Close the editor and click Publish changes from your site settings.

Once applied, your custom JavaScript resources will load on every page of the theme, directly after the theme’s own resources.

Best Practices

Check browser support

Your custom JavaScript is running directly in the browser. For this reason, make sure you stick to JavaScript syntax and features that are generally supported amongst browsers. If you’re unsure, use a resource like caniuse.com to check browser support.

Remove html elements from code snippets provided by third-party service

The help center theme does not allow you to insert HTML but only JavaScript code. Some third-party services do provide their integrations only as snippets of HTML code and assume that you are able to insert those scripts into your HTML files. They often provide script tags that contain JavaScript code and instruct you to paste this HTML before the end of the </head> tag of your page.

Since you cannot insert HTML, simply remove all HTML elements and insert only the JavaScript code that is between the <script> and </script> tags.

Avoid manipulating DOM elements whenever possible

We highly recommend that you avoid to manipulate the Document Object Model (DOM) elements of your site whenever possible. The selectors that you use to access parts of the page can change in future updates of the help center theme. Also, your manipulations to dymanic parts of the page (e.g. the page tree, the table of contents) may be lost if these parts are updated by Scroll Sites.

Safety measures you can take:

  • Keep your DOM manipulations to an absolute minimum.

  • Limit your DOM manipulations to the non-dynamic parts of the page (e.g. the article content).

If your custom JavaScript sets cookies or tracks visitors, we recommend enabling cookie consent management in the theme configurator and running your script only if the visitor has accepted the matching cookie category.

Use the following API to decide if you should execute your script:

API

Description

sts.cookies.acceptedCategory(category: string)

Returns true if the visitor accepted the specified cookie category, otherwise false.

Available categories:

  • functional

  • analytics

  • marketing

Before the visitor makes a choice, the result depends on your settings:

  • Consent dialog disabled: always true

  • Consent mode opt-out: true

  • Consent mode opt-in: false

JavaScript
if (sts.cookies.acceptedCategory('analytics')) {
  console.log('user accepted the analytics category');
}

sts.cookies.on('change', callback: (categories: string[]) => void)

The callback is invoked when the visitor first gives consent and whenever they change their cookie preferences. It receives:

  • On first consent: the accepted categories.

  • On later changes: the categories that changed, whether accepted or revoked.

The callback doesn't run on page load or when the consent dialog is disabled, and can run more than once per decision. Check acceptedCategory both when your script starts and inside the callback:

JavaScript
let loaded = false;

function loadAnalytics() {
  if (loaded || !sts.cookies.acceptedCategory('analytics')) {
    return;
  }
  loaded = true;
  // your analytics code here
}

loadAnalytics();
sts.cookies.on('change', loadAnalytics);

Revoking consent doesn't undo what your script already did. To react to a revocation, for example to remove cookies, check acceptedCategory in the callback and clean up yourself.

Limit script execution to specific pages

You can limit a script to specific pages in your site using the page’s content ID. This lets you invoke code only on those specified pages.

You can get the Confluence content ID using one of the following methods:

  • Navigate to that page inside Confluence and copy it from the URL
    Example: /pages/123456789/My+page+title.

  • Use your browser’s developer tools to inspect your page’s source. The content id is set right on the html element at the very top of your site’s source.
    Example: <html data-confluence-content-id="123456789">...</html>

Add the following line before your custom JavaScript code and insert your ID to limit the execution of your JavaScript to that specific page:

JavaScript
if (sts.confluence.contentId === 'YOUR_ID') {
  // your code here
}

Loading external scripts

Use the sts.loadScript(url:string): Promise<void> function to load external scripts into your Scroll site’s pages. It returns a Promise that gets resolved once the script has been loaded.

So add the following code to your custom JS to load an external script and wait for it to be fully loaded:

JavaScript
sts.loadScript('https://...').then(() => {
  console.log("External script has been loaded!");
});

Know and inform about third-party resources

Make sure you only load code from trusted sources such as your own servers, trusted services you would like to integrate with, or trusted CDNs.

If you load and use third-party resources, inform your site visitors about it by updating your privacy statement.

Trouble With Your Site After Adding JavaScript?

Is your site displaying errors or not working as expected? To exclude your custom JS as the root cause of the problem, we recommend testing your site without any custom JS applied.

Add ?disable-custom-overrides=true as a parameter to a Scroll site’s URL in the browser to exclude the custom resources from the theme.

Last updated: