Docs: Add documentation for CustomScript addon (#12623)

Copilot · humitos · ericholscher · web-flow · commit 672ece56d3cd · 2025-12-09T07:57:50.000-08:00
- [x] Understand the existing addons documentation structure - [x] Review the CustomScript addon feature implementation and usage - [x] Create documentation for the CustomScript addon in dedicated `docs/user/custom-script.rst` file - [x] Document the `window.ReadTheDocsEventData` flag for accessing addons data - [x] Add information about contacting support to enable the feature - [x] Include an example of how to use this feature - [x] Build and verify the documentation renders correctly - [x] Run code review on documentation changes - [x] Run security scanning (no code changes detected) - [x] Address PR feedback: add Custom Script to initial features list in `addons.rst` - [x] Address PR feedback: update code comments for better clarity - [x] Address PR feedback: move Custom Script documentation to separate file following addon documentation pattern  <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>Addons: add documentation for `CustomScript`</issue_title> > <issue_description>We need to document this addon and put some examples on how to solve common issues with this feature. > > * Refs: #11758 > * Requires: #11774 > * Requires: readthedocs/ext-theme#527 > * Requires: https://github.com/readthedocs/addons/pull/474</issue_description> > > <agent_instructions>We want to document this feature, even it's not exposed in the UI. Tell people to contact support if they want to make usage of this feature. > > Explain the flag we expose in `window` object. > > Mention an example of what this feature is useful for.</agent_instructions> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > <comment_new><author>@ericholscher</author><body> > We actually aren't exposing this to users -- should we, and write docs for it? </body></comment_new> > <comment_new><author>@humitos</author><body> > Yeah. I think it's fine to have small docs for this addon. It's not polished/perfect, but it's useful. We can add the other features mentioned in the description of the issue in the following iteration when more people are using it and requesting for upgrades.</body></comment_new> > </comments> > </details> - Fixes #11775  --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: humitos <244656+humitos@users.noreply.github.com> Co-authored-by: ericholscher <25510+ericholscher@users.noreply.github.com> Co-authored-by: Manuel Kaufmann <humitos@gmail.com>
diff --git a/docs/user/addons.rst b/docs/user/addons.rst
@@ -32,6 +32,9 @@ and can be accessed via hotkeys or on screen UI elements.
 :doc:`Search analytics </search-analytics>`
     Understand what your users are searching for
 
+:doc:`Custom script </custom-script>`
+    Inject custom JavaScript into your documentation
+
 Configuring Read the Docs Addons
 --------------------------------
 
diff --git a/docs/user/custom-script.rst b/docs/user/custom-script.rst
@@ -0,0 +1,57 @@
+Custom script
+=============
+
+The Custom Script addon allows you to inject a custom JavaScript file into your documentation at serve time.
+This enables you to modify or enhance frozen documentation without rebuilding it.
+
+.. note::
+
+   The Custom Script addon is not currently exposed in the user interface.
+   If you would like to use this feature,
+   please :doc:`contact support </support>`.
+
+Using custom scripts
+--------------------
+
+This addon allows specifying a URL to a JavaScript file that will be injected into all pages of your documentation.
+The script can be hosted on Read the Docs itself (as a relative URL) or on an external server (as an absolute URL).
+
+Common use cases for custom scripts include:
+
+* Fixing bugs or adding features to frozen documentation
+* Injecting analytics or tracking code
+* Customizing the appearance or behavior of specific documentation versions
+
+Accessing Addons data from your script
+--------------------------------------
+
+Custom scripts are loaded asynchronously after the initial page load,
+which means the ``readthedocs-addons-data-ready`` event has already been fired by the time your script executes.
+To access the Addons data from your custom script,
+check the ``window.ReadTheDocsEventData`` object first,
+then subscribe to the event for future updates (for example, when the URL changes in a single-page application):
+
+.. code-block:: javascript
+
+    function handleReadTheDocsData(data) {
+      // Access the Addons data here
+      console.log("Project slug:", data.projects.current.slug);
+
+      // You can filter by version to apply changes selectively
+      if (data.versions.current.slug === "v3.0") {
+        // Do something specific for version v3.0
+      }
+    }
+
+    // The event "readthedocs-addons-data-ready" has been already fired when this script is run.
+    // We need to check for `window.ReadTheDocsEventData` first, and if it's available
+    // use that data to call the handler.
+    if (window.ReadTheDocsEventData !== undefined) {
+      handleReadTheDocsData(window.ReadTheDocsEventData.data());
+    }
+
+    // After that, we subscribe to the Read the Docs Addons event to access data
+    // on future dispatchs (e.g. when a URL changes on a SPA)
+    document.addEventListener("readthedocs-addons-data-ready", function (event) {
+      handleReadTheDocsData(event.detail.data());
+    });
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -65,6 +65,7 @@ Read the Docs: documentation simplified
    /server-side-search/index
    /server-side-search/syntax
    /flyout-menu
+   /custom-script
 
 .. toctree::
    :maxdepth: 2
