diff --git a/docs/user/addons.rst b/docs/user/addons.rst index e2bdfdda4aa..98a701f92bf 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 +:doc:`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 new file mode 100644 index 00000000000..7528ae9196c --- /dev/null +++ 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 `. + +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 index 92c9b626ea2..e6b438300ae 100644 --- 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