Add Addons customization docs

docs/user/addons.rst

@@ -46,8 +46,321 @@ Individual configuration options for each addon are available in :guilabel:`Sett
 Addons data and customization
 -----------------------------
 
-If you'd like to do a custom integration with the data used to render Addons,
-you can learn more about this in our :ref:`flyout-menu:custom event integration` docs.
+Addons can be customized using CSS variables and the data used by Addons can be accessed using a custom event.
+
+CSS variable customization
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Addons use CSS custom properties (`CSS variables <https://developer.mozilla.org/en-US/docs/Web/CSS/--*>`_) to allow for easy customization.
+To customize addons, add CSS variable definitions to your theme's CSS:
+
+.. code-block:: css
+
+    :root {
+        /* Reduce Read the Docs' flyout font a little bit */
+        --readthedocs-flyout-font-size: 0.7rem;
+
+        /* Reduce Read the Docs' notification font a little bit */
+        --readthedocs-notification-font-size: 0.8rem;
+
+        /* This customization is not yet perfect because we can't change the `line-height` yet. */
+        /* See https://github.com/readthedocs/addons/issues/197 */
+        --readthedocs-search-font-size: 0.7rem;
+    }
+
+CSS variables reference
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. Got this with: grep -ho -- '--readthedocs-[a-zA-Z0-9-]*' *.css | sort -u
+
+.. dropdown:: Click to see all available CSS variables
+
+    **Global variables**
+
+    - ``--readthedocs-font-size``
+
+    **Flyout menu**
+
+    - ``--readthedocs-flyout-background-color``
+    - ``--readthedocs-flyout-color``
+    - ``--readthedocs-flyout-current-version-color``
+    - ``--readthedocs-flyout-font-family``
+    - ``--readthedocs-flyout-font-size``
+    - ``--readthedocs-flyout-header-font-size``
+    - ``--readthedocs-flyout-item-link-color``
+    - ``--readthedocs-flyout-link-color``
+    - ``--readthedocs-flyout-section-heading-color``
+
+    **Notifications**
+
+    - ``--readthedocs-notification-background-color``
+    - ``--readthedocs-notification-color``
+    - ``--readthedocs-notification-font-family``
+    - ``--readthedocs-notification-font-size``
+    - ``--readthedocs-notification-link-color``
+    - ``--readthedocs-notification-title-background-color``
+    - ``--readthedocs-notification-title-color``
+    - ``--readthedocs-notification-toast-font-size``
+
+    **Search**
+
+    - ``--readthedocs-search-backdrop-color``
+    - ``--readthedocs-search-color``
+    - ``--readthedocs-search-content-background-color``
+    - ``--readthedocs-search-content-border-color``
+    - ``--readthedocs-search-filters-border-color``
+    - ``--readthedocs-search-font-family``
+    - ``--readthedocs-search-font-size``
+    - ``--readthedocs-search-footer-background-color``
+    - ``--readthedocs-search-footer-code-background-color``
+    - ``--readthedocs-search-footer-code-border-color``
+    - ``--readthedocs-search-input-background-color``
+    - ``--readthedocs-search-result-section-border-color``
+    - ``--readthedocs-search-result-section-color``
+    - ``--readthedocs-search-result-section-highlight-color``
+    - ``--readthedocs-search-result-section-subheading-color``
+
+You can find default values and full CSS in our `Addons source <https://github.com/readthedocs/addons/tree/main/src>`_.
+
+Custom event integration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Read the Docs provides a custom event ``readthedocs-addons-data-ready`` that allows you to access the Addons data and integrate it into your theme or documentation.
+The event provides access to the version data, project information, and other Addons configuration.
+
+To use the custom event:
+
+1. Add the required meta tag to your HTML template:
+
+   .. code-block:: html
+
+      <meta name="readthedocs-addons-api-version" content="1" />
+
+2. Add a JavaScript event listener to handle the data:
+
+   .. code-block:: javascript
+
+      document.addEventListener(
+        "readthedocs-addons-data-ready",
+        function (event) {
+          // Access the addons data
+          const config = event.detail.data();
+
+          // Example: Create a version selector
+          const versions = config.versions.active.map(version => ({
+            slug: version.slug,
+            url: version.urls.documentation
+          }));
+
+          // Use the data to build your UI
+          console.log('Available versions:', versions);
+        }
+      );
+
+Event data reference
+^^^^^^^^^^^^^^^^^^^^
+
+The ``event.detail.data()`` object contains all the Addons configuration, including:
+
+* ``addons`` - Individual addon configurations
+* ``builds.current`` - Details about the current build
+* ``projects.current`` - Current project details
+* ``projects.translations`` - Available translations
+* ``versions.current`` - Details about the current version
+* ``versions.active`` - List of all active and not hidden versions
+
+.. dropdown:: Click to see an example of the Addons data
+
+    .. code-block:: json
+
+        {
+        "addons": {
+            "Most of this config is currently for internal use.": "We are working on making this more public.",
+        },
+        "api_version": "1",
+        "builds": {
+            "current": {
+                "commit": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
+                "created": "2025-01-07T16:02:16.842871Z",
+                "duration": 78,
+                "error": "",
+                "finished": "2025-01-07T16:03:34.842Z",
+                "id": 26773762,
+                "project": "docs",
+                "state": {
+                    "code": "finished",
+                    "name": "Finished"
+                },
+                "success": true,
+                "urls": {
+                    "build": "https://readthedocs.org/projects/docs/builds/26773762/",
+                    "project": "https://readthedocs.org/projects/docs/",
+                    "version": "https://readthedocs.org/projects/docs/version/stable/edit/"
+                },
+                "version": "stable"
+            }
+        },
+        "domains": {
+            "dashboard": "readthedocs.org"
+        },
+        "projects": {
+            "current": {
+                "created": "2016-12-20T06:26:09.098922Z",
+                "default_branch": "main",
+                "default_version": "stable",
+                "external_builds_privacy_level": "public",
+                "homepage": null,
+                "id": 74581,
+                "language": {
+                    "code": "en",
+                    "name": "English"
+                },
+                "modified": "2024-11-13T17:09:09.007795Z",
+                "name": "docs",
+                "privacy_level": "public",
+                "programming_language": {
+                    "code": "py",
+                    "name": "Python"
+                },
+                "repository": {
+                    "type": "git",
+                    "url": "https://github.com/readthedocs/readthedocs.org"
+                },
+                "single_version": false,
+                "slug": "docs",
+                "subproject_of": null,
+                "tags": [
+                    "docs",
+                    "python",
+                    "sphinx-doc"
+                ],
+                "translation_of": null,
+                "urls": {
+                    "builds": "https://readthedocs.org/projects/docs/builds/",
+                    "documentation": "https://docs.readthedocs.io/en/stable/",
+                    "downloads": "https://readthedocs.org/projects/docs/downloads/",
+                    "home": "https://readthedocs.org/projects/docs/",
+                    "versions": "https://readthedocs.org/projects/docs/versions/"
+                },
+                "users": [
+                    {
+                        "username": "eric"
+                    },
+                    {
+                        "username": "davidfischer"
+                    },
+                    {
+                        "username": "humitos"
+                    },
+                    {
+                        "username": "plaindocs"
+                    },
+                    {
+                        "username": "agj"
+                    },
+                    {
+                        "username": "stsewd"
+                    }
+                ],
+                "versioning_scheme": "multiple_versions_with_translations"
+            },
+            "translations": []
+        },
+        "readthedocs": {
+            "analytics": {
+                "code": "UA-17997319-1"
+            }
+        },
+        "versions": {
+            "active": [
+                {
+                    "active": true,
+                    "aliases": [],
+                    "built": true,
+                    "downloads": {
+                        "epub": "https://docs.readthedocs.io/_/downloads/en/stable/epub/",
+                        "htmlzip": "https://docs.readthedocs.io/_/downloads/en/stable/htmlzip/"
+                    },
+                    "hidden": false,
+                    "id": 2604018,
+                    "identifier": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
+                    "privacy_level": "public",
+                    "ref": "11.18.0",
+                    "slug": "stable",
+                    "type": "tag",
+                    "urls": {
+                        "dashboard": {
+                            "edit": "https://readthedocs.org/projects/docs/version/stable/edit/"
+                        },
+                        "documentation": "https://docs.readthedocs.io/en/stable/",
+                        "vcs": "https://github.com/readthedocs/readthedocs.org/tree/11.18.0/"
+                    },
+                    "verbose_name": "stable"
+                }
+            ],
+            "current": {
+                "active": true,
+                "aliases": [],
+                "built": true,
+                "downloads": {
+                    "epub": "https://docs.readthedocs.io/_/downloads/en/stable/epub/",
+                    "htmlzip": "https://docs.readthedocs.io/_/downloads/en/stable/htmlzip/"
+                },
+                "hidden": false,
+                "id": 2604018,
+                "identifier": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
+                "privacy_level": "public",
+                "ref": "11.18.0",
+                "slug": "stable",
+                "type": "tag",
+                "urls": {
+                    "dashboard": {
+                        "edit": "https://readthedocs.org/projects/docs/version/stable/edit/"
+                    },
+                    "documentation": "https://docs.readthedocs.io/en/stable/",
+                    "vcs": "https://github.com/readthedocs/readthedocs.org/tree/11.18.0/"
+                },
+                "verbose_name": "stable"
+            }
+        }
+
+You can see a live example of this in our `Addons API response for these docs <https://docs.readthedocs.io/_/addons/?client-version=0.22.0&api-version=1&project-slug=docs&version-slug=stable>`_.
+
+Example: creating a version selector
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here's a complete example showing how to create a version selector using the Addons data:
+
+.. code-block:: javascript
+
+    document.addEventListener(
+      "readthedocs-addons-data-ready",
+      function (event) {
+        const config = event.detail.data();
+
+        // Create the version selector HTML
+        const versionSelector = `
+          <div class="version-selector">
+            <select onchange="window.location.href=this.value">
+              <option value="${config.versions.current.urls.documentation}">
+                ${config.versions.current.slug}
+              </option>
+              ${config.versions.active
+                .filter(v => v.slug !== config.versions.current.slug)
+                .map(version => `
+                  <option value="${version.urls.documentation}">
+                    ${version.slug}
+                  </option>
+                `).join('')}
+            </select>
+          </div>
+        `;
+
+        // Insert the version selector into your page
+        document.querySelector('#your-target-element')
+          .insertAdjacentHTML('beforeend', versionSelector);
+      }
+    );
 
 Diving deeper
 -------------