From 6db7b8ee1b5c24ea142488210e86385ffcab95c0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 1 Dec 2025 11:09:12 +0000 Subject: [PATCH 1/4] Initial plan From 9ed281a1f19af062a90d320d23df7495e63f7252 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 1 Dec 2025 11:14:53 +0000 Subject: [PATCH 2/4] Add documentation for CustomScript addon feature Co-authored-by: humitos <244656+humitos@users.noreply.github.com> --- docs/user/addons.rst | 55 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/user/addons.rst b/docs/user/addons.rst index e2bdfdda4aa..a56cd6b7cbe 100644 --- a/docs/user/addons.rst +++ b/docs/user/addons.rst @@ -388,6 +388,61 @@ Here's a complete example showing how to create a version selector using the Add } ); +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 `. + +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 after the ``readthedocs-addons-data-ready`` event has been fired. +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 has already fired when custom scripts load. + // Check for window.ReadTheDocsEventData first. + if (window.ReadTheDocsEventData !== undefined) { + handleReadTheDocsData(window.ReadTheDocsEventData.data()); + } + + // Subscribe to the event for future data updates + document.addEventListener("readthedocs-addons-data-ready", function (event) { + handleReadTheDocsData(event.detail.data()); + }); + Diving deeper ------------- From 013e2bffa351d47773224dd30d054676075c1fcc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 1 Dec 2025 11:16:21 +0000 Subject: [PATCH 3/4] Improve clarity in CustomScript documentation Co-authored-by: humitos <244656+humitos@users.noreply.github.com> --- docs/user/addons.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user/addons.rst b/docs/user/addons.rst index a56cd6b7cbe..dc566d0c64c 100644 --- a/docs/user/addons.rst +++ b/docs/user/addons.rst @@ -415,7 +415,8 @@ Common use cases for custom scripts include: Accessing Addons data from your script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Custom scripts are loaded after the ``readthedocs-addons-data-ready`` event has been fired. +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): From 2abf4e433c217a2cbd569297205424a69e457670 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 21:14:13 +0000 Subject: [PATCH 4/4] Address PR feedback: add Custom Script to features list and update code comments Co-authored-by: ericholscher <25510+ericholscher@users.noreply.github.com> --- docs/user/addons.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/user/addons.rst b/docs/user/addons.rst index dc566d0c64c..0a188502eaa 100644 --- 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 ` Understand what your users are searching for +:ref:`Custom script ` + Inject custom JavaScript into your documentation + Configuring Read the Docs Addons -------------------------------- @@ -433,13 +436,15 @@ then subscribe to the event for future updates (for example, when the URL change } } - // The event has already fired when custom scripts load. - // Check for window.ReadTheDocsEventData first. + // 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()); } - // Subscribe to the event for future data updates + // 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()); });