Try CSS variable again #545

agjohnson · 2025-02-19T03:17:59Z

Potentially replaces #492

Use our heuristic to detect the documentation tool/theme and add specific `--readthedocs-*` CSS variables based on that for known tools/themes. Reference: readthedocs/readthedocs.org#11849 (comment)

This moves the inner CSS rules from inside the shadow DOM to the parent DOM. This allows users to still set a `--readthedocs-font-size` and similar variables.

Merge branch 'humitos/footer-style' into agj/footer-style

agjohnson · 2025-02-19T03:27:44Z

public/_/readthedocs-addons.json

This file is for illustration only.

agjohnson · 2025-02-19T03:27:57Z

public/global.css

Also for illustration only

agjohnson · 2025-02-19T03:28:07Z

public/index.html

And also not needed

We can probably create another HTML file to keep in the repository and show this as example 👍🏼

agjohnson · 2025-02-19T03:42:15Z

Marking this for review so it doesn't get lost again. @humitos can you look at this and see if it makes sense to you?

There are some extra changes here that can be removed before merging, it's just for example.

Right now, with all of the changes and the defaults applied with the extra files, here is what the flyout and notification look like:

humitos

I think this is a good pattern and it's going in a good direction.

Here you have my observations:

I'd like to write the CSS code in a CSS file
We should have a new HTML file showing an example that overrides the defaults
There are some properties that were calculated based in others and now they are fixed values
Some defaults are not defined (eg. font family)

humitos · 2025-02-26T12:32:09Z

src/defaults.js

 /*
 * Specific styles based on documentation tools and themes
 *
 * Usage of `@layer` at-rule pushes this rules down a step in
 * precedence/priority. This allows a user `:root` rule to override these
 * values.
 **/
+defaultStyleSheet.replaceSync(`


I don't like too much that we are writing all these CSS in a JS file. Can't we just have a defaults.css file and import it here instead?

Actually, I don't really understand why you migrated from doctools.css to default.js. You had to change the code in application.js as well -- why not just keep the doctools.css (or defaults.css if you want) but keeping the CSS extension and importing the CSS from application.js as we were doing?

It can't be an imported CSS file (Lit stylesheet) as these lack all of the functionality of the native CSSStyleSheet instances, namely insertRule() used below.

So I would not make this a CSS import, what is here is easiest. There are only a few lines of CSS here, so this doesn't feel like a barrier. If we eventually find we would gain some value from splitting this out to another CSS file, we can create a merge strategy that includes a separate file first.

src/defaults.js

humitos · 2025-02-26T12:37:01Z

public/index.html

We can probably create another HTML file to keep in the repository and show this as example 👍🏼

humitos · 2025-02-26T12:40:12Z

src/flyout.css

+    --readthedocs-flyout-font-family: var(--readthedocs-font-family);
+    --readthedocs-flyout-font-size: var(--readthedocs-font-size);


It seems we need to define these in defaults.js, right? I mean, --readthedocs-font-*. I didn't find where they are defined.

Yup correct. This was probably lost in merging.

humitos · 2025-02-26T12:41:11Z

src/flyout.css

-  color: var(--readthedocs-flyout-current-version-color, #27ae60);
+  color: var(--readthedocs-flyout-current-version-color);
+  font-size: var(--readthedocs-flyout-header-font-size);
+  margin-left: 10px;


This property is new. Is this correct?

src/flyout.css

hgoel0 · 2025-04-14T13:09:19Z

Thank you for the work on this. Would it be possible to also test this against the pydata theme?

I am happy to deploy to our rtd to test and provide feedback.

flying-sheep · 2025-04-22T10:55:57Z

See here for some currently hardcoded colors: #570 (comment)

Here’s an adapter for the pydata theme I’m currently using:

:root {
    --readthedocs-search-backdrop-color: var(--pst-color-shadow);
    --readthedocs-search-color: var(--pst-color-text-base);
    --readthedocs-search-content-background-color: var(--pst-color-background);
    --readthedocs-search-content-border-color: var(--pst-color-border);
    --readthedocs-search-filters-border-color: var(--pst-color-border);
    --readthedocs-search-font-family: var(--pst-font-family-base);
    --readthedocs-search-font-size: var(--pst-font-size-base);
    --readthedocs-search-footer-background-color: var(--pst-color-on-background);
    --readthedocs-search-footer-code-background-color: var(--pst-color-surface);
    --readthedocs-search-footer-code-border-color: var(--pst-color-border);
    --readthedocs-search-input-background-color: var(--pst-color-surface);
    --readthedocs-search-result-section-border-color: var(--pst-color-border);
    --readthedocs-search-result-section-color: var(--pst-color-link);
    --readthedocs-search-result-section-highlight-color: var(--pst-color-accent);
    --readthedocs-search-result-section-subheading-color: var(--pst-color-text-muted);
}

agjohnson · 2025-04-23T22:04:09Z

See here for some currently hardcoded colors: #570 (comment)

I had skipped the search addon for this first pass, but it probably makes sense to also use these changes here. I'll replicate these variables and the new ones from your #571 in this PR 👍

humitos and others added 21 commits December 16, 2024 11:44

Add styles based on the documentation tool

00f72e0

Use our heuristic to detect the documentation tool/theme and add specific `--readthedocs-*` CSS variables based on that for known tools/themes. Reference: readthedocs/readthedocs.org#11849 (comment)

Use a reactive property to add specific classes

24d7869

Use tool=sphinx tool-theme=furo to add CSS rules

f3477b7

Remove unused code

053d931

Update furo font size

8c337ea

Update MkDocs Material font size

9d08961

Useful for Jupyter Book and others

12057bf

Style for Antora

28bb43c

Update snapshots to match tool= and tool-theme= attrs

434f187

Better comment

718b52a

Rename attribute with a data- prefix

531c7e2

Adjust style a little more

7f099cc

Show example of setting attributes and variables at parent DOM

fe1319f

This moves the inner CSS rules from inside the shadow DOM to the parent DOM. This allows users to still set a `--readthedocs-font-size` and similar variables.

Show example of setting attributes and variables at parent DOM (#484)

d6e86c6

This moves the inner CSS rules from inside the shadow DOM to the parent DOM. This allows users to still set a `--readthedocs-font-size` and similar variables.

Small tweaks to font sizes

1446007

Fix some tests

ed87f06

Handle error when checking mdBook

4d2a219

More fixes

6b5db39

Update font sizes

12f1b3f

Merge branch 'humitos/footer-style' into agj/footer-style

Working example of CSS layer defaults

5d2a33f

Merge branch 'main' into agj/css-variable-root-defaults

1b2ce13

agjohnson commented Feb 19, 2025

View reviewed changes

public/_/readthedocs-addons.json Outdated

Copy link

Contributor Author

agjohnson Feb 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is for illustration only.

agjohnson commented Feb 19, 2025

View reviewed changes

public/global.css Outdated

Copy link

Contributor Author

agjohnson Feb 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also for illustration only

agjohnson commented Feb 19, 2025

View reviewed changes

agjohnson added 5 commits February 18, 2025 19:29

Hack not needed because this is a native CSSStyleSheet

a348a9e

Bad merge?

d6c139b

Drop unused doctools.css

047c286

Tune var usage and defaults

f847c0e

Lint

69dfc0a

agjohnson marked this pull request as ready for review February 19, 2025 03:42

agjohnson requested review from humitos and a team as code owners February 19, 2025 03:42

agjohnson mentioned this pull request Feb 19, 2025

Example to show settings all varialbes at :root explicitly #492

Closed

Relint

5844acf

agjohnson self-assigned this Feb 20, 2025

humitos reviewed Feb 26, 2025

View reviewed changes

agjohnson added 2 commits March 21, 2025 16:59

Set global font-size and font-family

92d9b08

Add CSS variable defaults for other addons

dae5c61

humitos mentioned this pull request Apr 14, 2025

Remove Hard Coded CSS Colors #571

Closed

agjohnson requested a review from humitos April 23, 2025 16:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Try CSS variable again #545

Try CSS variable again #545

agjohnson commented Feb 19, 2025

agjohnson Feb 19, 2025

agjohnson Feb 19, 2025

agjohnson Feb 19, 2025

humitos Feb 26, 2025

agjohnson commented Feb 19, 2025

humitos left a comment

humitos Feb 26, 2025

humitos Feb 26, 2025

agjohnson Mar 21, 2025

humitos Feb 26, 2025

humitos Feb 26, 2025

agjohnson Mar 21, 2025

humitos Feb 26, 2025

hgoel0 commented Apr 14, 2025

flying-sheep commented Apr 22, 2025 •

edited

Loading

agjohnson commented Apr 23, 2025 •

edited

Loading

		--readthedocs-flyout-font-family: var(--readthedocs-font-family);
		--readthedocs-flyout-font-size: var(--readthedocs-font-size);

Try CSS variable again #545

Are you sure you want to change the base?

Try CSS variable again #545

Conversation

agjohnson commented Feb 19, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson commented Feb 19, 2025

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hgoel0 commented Apr 14, 2025

flying-sheep commented Apr 22, 2025 • edited Loading

agjohnson commented Apr 23, 2025 • edited Loading

flying-sheep commented Apr 22, 2025 •

edited

Loading

agjohnson commented Apr 23, 2025 •

edited

Loading