Skip to content

Commit e7afae1

Browse files
ericholscheragjohnson
ericholscher
and
agjohnson
authored
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. <!-- 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 <aj@ohess.org>
1 parent 46dee70 commit e7afae1

File tree

1 file changed

+315
-2
lines changed

1 file changed

+315
-2
lines changed

‎docs/user/addons.rst‎

Lines changed: 315 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,321 @@ Individual configuration options for each addon are available in :guilabel:`Sett
4646
Addons data and customization
4747
-----------------------------
4848

49-
If you'd like to do a custom integration with the data used to render Addons,
50-
you can learn more about this in our :ref:`flyout-menu:custom event integration` docs.
49+
Addons can be customized using CSS variables and the data used by Addons can be accessed using a custom event.
50+
51+
CSS variable customization
52+
~~~~~~~~~~~~~~~~~~~~~~~~~~
53+
54+
Addons use CSS custom properties (`CSS variables <https://developer.mozilla.org/en-US/docs/Web/CSS/--*>`_) to allow for easy customization.
55+
To customize addons, add CSS variable definitions to your theme's CSS:
56+
57+
.. code-block:: css
58+
59+
:root {
60+
/* Reduce Read the Docs' flyout font a little bit */
61+
--readthedocs-flyout-font-size: 0.7rem;
62+
63+
/* Reduce Read the Docs' notification font a little bit */
64+
--readthedocs-notification-font-size: 0.8rem;
65+
66+
/* This customization is not yet perfect because we can't change the `line-height` yet. */
67+
/* See https://github.com/readthedocs/addons/issues/197 */
68+
--readthedocs-search-font-size: 0.7rem;
69+
}
70+
71+
CSS variables reference
72+
^^^^^^^^^^^^^^^^^^^^^^^
73+
74+
.. Got this with: grep -ho -- '--readthedocs-[a-zA-Z0-9-]*' *.css | sort -u
75+
76+
.. dropdown:: Click to see all available CSS variables
77+
78+
**Global variables**
79+
80+
- ``--readthedocs-font-size``
81+
82+
**Flyout menu**
83+
84+
- ``--readthedocs-flyout-background-color``
85+
- ``--readthedocs-flyout-color``
86+
- ``--readthedocs-flyout-current-version-color``
87+
- ``--readthedocs-flyout-font-family``
88+
- ``--readthedocs-flyout-font-size``
89+
- ``--readthedocs-flyout-header-font-size``
90+
- ``--readthedocs-flyout-item-link-color``
91+
- ``--readthedocs-flyout-link-color``
92+
- ``--readthedocs-flyout-section-heading-color``
93+
94+
**Notifications**
95+
96+
- ``--readthedocs-notification-background-color``
97+
- ``--readthedocs-notification-color``
98+
- ``--readthedocs-notification-font-family``
99+
- ``--readthedocs-notification-font-size``
100+
- ``--readthedocs-notification-link-color``
101+
- ``--readthedocs-notification-title-background-color``
102+
- ``--readthedocs-notification-title-color``
103+
- ``--readthedocs-notification-toast-font-size``
104+
105+
**Search**
106+
107+
- ``--readthedocs-search-backdrop-color``
108+
- ``--readthedocs-search-color``
109+
- ``--readthedocs-search-content-background-color``
110+
- ``--readthedocs-search-content-border-color``
111+
- ``--readthedocs-search-filters-border-color``
112+
- ``--readthedocs-search-font-family``
113+
- ``--readthedocs-search-font-size``
114+
- ``--readthedocs-search-footer-background-color``
115+
- ``--readthedocs-search-footer-code-background-color``
116+
- ``--readthedocs-search-footer-code-border-color``
117+
- ``--readthedocs-search-input-background-color``
118+
- ``--readthedocs-search-result-section-border-color``
119+
- ``--readthedocs-search-result-section-color``
120+
- ``--readthedocs-search-result-section-highlight-color``
121+
- ``--readthedocs-search-result-section-subheading-color``
122+
123+
You can find default values and full CSS in our `Addons source <https://github.com/readthedocs/addons/tree/main/src>`_.
124+
125+
Custom event integration
126+
~~~~~~~~~~~~~~~~~~~~~~~~
127+
128+
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.
129+
The event provides access to the version data, project information, and other Addons configuration.
130+
131+
To use the custom event:
132+
133+
1. Add the required meta tag to your HTML template:
134+
135+
.. code-block:: html
136+
137+
<meta name="readthedocs-addons-api-version" content="1" />
138+
139+
2. Add a JavaScript event listener to handle the data:
140+
141+
.. code-block:: javascript
142+
143+
document.addEventListener(
144+
"readthedocs-addons-data-ready",
145+
function (event) {
146+
// Access the addons data
147+
const config = event.detail.data();
148+
149+
// Example: Create a version selector
150+
const versions = config.versions.active.map(version => ({
151+
slug: version.slug,
152+
url: version.urls.documentation
153+
}));
154+
155+
// Use the data to build your UI
156+
console.log('Available versions:', versions);
157+
}
158+
);
159+
160+
Event data reference
161+
^^^^^^^^^^^^^^^^^^^^
162+
163+
The ``event.detail.data()`` object contains all the Addons configuration, including:
164+
165+
* ``addons`` - Individual addon configurations
166+
* ``builds.current`` - Details about the current build
167+
* ``projects.current`` - Current project details
168+
* ``projects.translations`` - Available translations
169+
* ``versions.current`` - Details about the current version
170+
* ``versions.active`` - List of all active and not hidden versions
171+
172+
.. dropdown:: Click to see an example of the Addons data
173+
174+
.. code-block:: json
175+
176+
{
177+
"addons": {
178+
"Most of this config is currently for internal use.": "We are working on making this more public.",
179+
},
180+
"api_version": "1",
181+
"builds": {
182+
"current": {
183+
"commit": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
184+
"created": "2025-01-07T16:02:16.842871Z",
185+
"duration": 78,
186+
"error": "",
187+
"finished": "2025-01-07T16:03:34.842Z",
188+
"id": 26773762,
189+
"project": "docs",
190+
"state": {
191+
"code": "finished",
192+
"name": "Finished"
193+
},
194+
"success": true,
195+
"urls": {
196+
"build": "https://readthedocs.org/projects/docs/builds/26773762/",
197+
"project": "https://readthedocs.org/projects/docs/",
198+
"version": "https://readthedocs.org/projects/docs/version/stable/edit/"
199+
},
200+
"version": "stable"
201+
}
202+
},
203+
"domains": {
204+
"dashboard": "readthedocs.org"
205+
},
206+
"projects": {
207+
"current": {
208+
"created": "2016-12-20T06:26:09.098922Z",
209+
"default_branch": "main",
210+
"default_version": "stable",
211+
"external_builds_privacy_level": "public",
212+
"homepage": null,
213+
"id": 74581,
214+
"language": {
215+
"code": "en",
216+
"name": "English"
217+
},
218+
"modified": "2024-11-13T17:09:09.007795Z",
219+
"name": "docs",
220+
"privacy_level": "public",
221+
"programming_language": {
222+
"code": "py",
223+
"name": "Python"
224+
},
225+
"repository": {
226+
"type": "git",
227+
"url": "https://github.com/readthedocs/readthedocs.org"
228+
},
229+
"single_version": false,
230+
"slug": "docs",
231+
"subproject_of": null,
232+
"tags": [
233+
"docs",
234+
"python",
235+
"sphinx-doc"
236+
],
237+
"translation_of": null,
238+
"urls": {
239+
"builds": "https://readthedocs.org/projects/docs/builds/",
240+
"documentation": "https://docs.readthedocs.io/en/stable/",
241+
"downloads": "https://readthedocs.org/projects/docs/downloads/",
242+
"home": "https://readthedocs.org/projects/docs/",
243+
"versions": "https://readthedocs.org/projects/docs/versions/"
244+
},
245+
"users": [
246+
{
247+
"username": "eric"
248+
},
249+
{
250+
"username": "davidfischer"
251+
},
252+
{
253+
"username": "humitos"
254+
},
255+
{
256+
"username": "plaindocs"
257+
},
258+
{
259+
"username": "agj"
260+
},
261+
{
262+
"username": "stsewd"
263+
}
264+
],
265+
"versioning_scheme": "multiple_versions_with_translations"
266+
},
267+
"translations": []
268+
},
269+
"readthedocs": {
270+
"analytics": {
271+
"code": "UA-17997319-1"
272+
}
273+
},
274+
"versions": {
275+
"active": [
276+
{
277+
"active": true,
278+
"aliases": [],
279+
"built": true,
280+
"downloads": {
281+
"epub": "https://docs.readthedocs.io/_/downloads/en/stable/epub/",
282+
"htmlzip": "https://docs.readthedocs.io/_/downloads/en/stable/htmlzip/"
283+
},
284+
"hidden": false,
285+
"id": 2604018,
286+
"identifier": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
287+
"privacy_level": "public",
288+
"ref": "11.18.0",
289+
"slug": "stable",
290+
"type": "tag",
291+
"urls": {
292+
"dashboard": {
293+
"edit": "https://readthedocs.org/projects/docs/version/stable/edit/"
294+
},
295+
"documentation": "https://docs.readthedocs.io/en/stable/",
296+
"vcs": "https://github.com/readthedocs/readthedocs.org/tree/11.18.0/"
297+
},
298+
"verbose_name": "stable"
299+
}
300+
],
301+
"current": {
302+
"active": true,
303+
"aliases": [],
304+
"built": true,
305+
"downloads": {
306+
"epub": "https://docs.readthedocs.io/_/downloads/en/stable/epub/",
307+
"htmlzip": "https://docs.readthedocs.io/_/downloads/en/stable/htmlzip/"
308+
},
309+
"hidden": false,
310+
"id": 2604018,
311+
"identifier": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
312+
"privacy_level": "public",
313+
"ref": "11.18.0",
314+
"slug": "stable",
315+
"type": "tag",
316+
"urls": {
317+
"dashboard": {
318+
"edit": "https://readthedocs.org/projects/docs/version/stable/edit/"
319+
},
320+
"documentation": "https://docs.readthedocs.io/en/stable/",
321+
"vcs": "https://github.com/readthedocs/readthedocs.org/tree/11.18.0/"
322+
},
323+
"verbose_name": "stable"
324+
}
325+
}
326+
327+
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>`_.
328+
329+
Example: creating a version selector
330+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
331+
332+
Here's a complete example showing how to create a version selector using the Addons data:
333+
334+
.. code-block:: javascript
335+
336+
document.addEventListener(
337+
"readthedocs-addons-data-ready",
338+
function (event) {
339+
const config = event.detail.data();
340+
341+
// Create the version selector HTML
342+
const versionSelector = `
343+
<div class="version-selector">
344+
<select onchange="window.location.href=this.value">
345+
<option value="${config.versions.current.urls.documentation}">
346+
${config.versions.current.slug}
347+
</option>
348+
${config.versions.active
349+
.filter(v => v.slug !== config.versions.current.slug)
350+
.map(version => `
351+
<option value="${version.urls.documentation}">
352+
${version.slug}
353+
</option>
354+
`).join('')}
355+
</select>
356+
</div>
357+
`;
358+
359+
// Insert the version selector into your page
360+
document.querySelector('#your-target-element')
361+
.insertAdjacentHTML('beforeend', versionSelector);
362+
}
363+
);
51364

52365
Diving deeper
53366
-------------

0 commit comments

Comments
 (0)