Add Addons customization docs #11888
+317
−2
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -46,8 +46,323 @@ Individual configuration options for each addon are available in :guilabel:`Sett | |
| Addons data and customization | ||
| ----------------------------- | ||
|
|
||
| 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-dd-font-size`` | ||
| - ``--readthedocs-flyout-dt-font-size`` | ||
|
Comment on lines
+87
to
+88
There was a problem hiding this comment. @agjohnson mentioned these |
||
| - ``--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>`_. | ||
|
There was a problem hiding this comment. This could be a |
||
|
|
||
| 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>`_. | ||
|
There was a problem hiding this comment. I don't think a tip is really useful? I don't want to highlight this too visually, and it's the only content in the section that is expanded by default. |
||
|
|
||
| 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 | ||
| ------------- | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I left a comment about if users should use
remorpxhere in readthedocs/addons#488 (comment) because it's not 100% clear to me yet.