From e7afae1fa39a16f6120f3dc4d06608710e0b3de1 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Mon, 13 Jan 2025 14:50:13 -0800 Subject: [PATCH] Add Addons customization docs (#11888) This is start for this work, and mostly just pulls examples from the Mkdocs page over to the Addons docs. I think there's more to do here with examples, but I think this is a reasonable starting point. --- :books: Documentation previews :books: - User's documentation (`docs`): https://docs--11888.org.readthedocs.build/en/11888/ - Developer's documentation (`dev`): https://dev--11888.org.readthedocs.build/en/11888/ --------- Co-authored-by: Anthony --- docs/user/addons.rst | 317 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 315 insertions(+), 2 deletions(-) diff --git a/docs/user/addons.rst b/docs/user/addons.rst index 46af2d3829d..dc3b0b92273 100644 --- a/docs/user/addons.rst +++ b/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 `_) 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 `_. + +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 + + + +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 `_. + +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 = ` +
+ +
+ `; + + // Insert the version selector into your page + document.querySelector('#your-target-element') + .insertAdjacentHTML('beforeend', versionSelector); + } + ); Diving deeper -------------