Skip to content

Commit

Permalink
Add Addons customization docs (#11888)
Browse files Browse the repository at this point in the history 
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.


<!-- readthedocs-preview docs start -->
---
:books: Documentation previews :books:

- User's documentation (`docs`):
https://docs--11888.org.readthedocs.build/en/11888/

<!-- readthedocs-preview docs end -->

<!-- readthedocs-preview dev start -->
- Developer's documentation (`dev`):
https://dev--11888.org.readthedocs.build/en/11888/

<!-- readthedocs-preview dev end -->

---------

Co-authored-by: Anthony <[email protected]>
  • Loading branch information
@ericholscher @agjohnson
ericholscher and agjohnson authored Jan 13, 2025
1 parent 46dee70 commit e7afae1
Showing 1 changed file with 315 additions and 2 deletions.
317 changes: 315 additions & 2 deletions docs/user/addons.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------
Expand Down

0 comments on commit e7afae1

Please sign in to comment.