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)

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 👍🏼

src/flyout.css

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

I re-review this and I think the pattern is correct 👍🏼

The last 3 bullets from my previous review are still valid: #545 (review)

agjohnson · 2025-05-01T01:54:51Z

We should have a new HTML file showing an example that overrides the defaults

You can add these variables on the existing example test page as a rule on html. I'm not sure there's a strong purpose yet for a development page like this yet as there isn't any way to validate what you are supposed to see with a page like that.

We can unit test some of these styles with web-test-runner though, and should probably eventually use a visual diffing tool like Happo to just automate this.

There are some properties that were calculated based in others and now they are fixed values

What are you referring to here? There are a few places that a complex calc(var(...) * 1.125) was replaced by a much simpler 1.125em, is this what you're referring to?

Some defaults are not defined (eg. font family)

This was already resolved.

agjohnson · 2025-05-01T02:00:25Z

I am still poking this as the search addon is quite chaotic on font-sizes. It overuses font-size and uses all sorts of different units are used for sizing and positioning: rem, em, px, and small. So the font size is customizable but it renders inconsistently:

humitos · 2025-05-06T09:41:11Z

What are you referring to here? There are a few places that a complex calc(var(...) * 1.125) was replaced by a much simpler 1.125em, is this what you're referring to?

Yes, I mentioned this at #545 (comment)

It seems you already replied to that and I've missed.

Just a basic font-size and color example, we can build on these as we go

agjohnson · 2025-05-07T17:01:00Z

I wrote up a quick example of what CSS style testing would look like in 4b683a3. I didn't do this across our addons or customization points yet, but this would be easy to expand on.

I'm going to push off fixing issues with font sizes in search to a later issue. The font size issue is a current bug with search already:

So I think we can continue with this from here. Follow up work to this issue can be:

Test this in production more
Tests: improve coverage on CSS customization unit tests
Search: fix inconsistent and static font size usage
Better addons documentation #577 to document customization and defaults better

agjohnson · 2025-05-07T17:09:05Z

src/search.css

+    --readthedocs-search-footer-code-border-color: #e1e4e5;
+    --readthedocs-search-input-background-color: #eaeaea;
+
+    /* `--readthedocs-search-result-section-highlight-color` is deprecated but


The result-section prefix confused me, as these rules target not the "section" -- ie the surrounding element around results -- but are instead for the individual results. So I think these should all be search-result-background-color not search-result-section-background-color, etc.

I don't remember exactly how this works, but I remember that a section can have multiple results -- if that helps 😄

There is a div.results that has all of the individual page .hit elements and each .hit can have multiple nested results. But the styles in these variables aren't affecting div.results, what I assumed section referred to. It's ambiguous enough it's worth removing either way.

.pre-commit-config.yaml

agjohnson · 2025-05-07T17:16:00Z

@humitos I'd take one last look at the change here. Notable changes at this point:

Slight CSS unit test coverage. Anything else to cover immediately?
Not a big deal, but I noticed that tests do need to load the default style sheets manually now. Without loading the defaults, unit tests load partially unstyled elements.
Some CSS variables have changed slightly

humitos · 2025-05-12T09:10:21Z

We can unit test some of these styles with web-test-runner though, and should probably eventually use a visual diffing tool like Happo to just automate this.

Yeah, no, I'm not talking about something complex like this. I was thinking of just having a page using the CSS variables with noticeable changes (very big flyout/search/etc) just to quickly see they have effect.

humitos · 2025-05-12T09:11:57Z

I am still poking this as the search addon is quite chaotic on font-sizes. It overuses font-size and uses all sorts of different units are used for sizing and positioning: rem, em, px, and small.

This was quickly copied from the old Sphinx extension without thinking too much about it or doing any modification. Feel free to re-structure it with a more modern pattern.

.pre-commit-config.yaml

src/defaults.css

src/notification.css

humitos · 2025-05-12T09:25:05Z

src/search.css

+    --readthedocs-search-footer-code-border-color: #e1e4e5;
+    --readthedocs-search-input-background-color: #eaeaea;
+
+    /* `--readthedocs-search-result-section-highlight-color` is deprecated but


I don't remember exactly how this works, but I remember that a section can have multiple results -- if that helps 😄

humitos · 2025-05-12T09:27:18Z

tests/flyout.test.html

+            const element = document.querySelector("readthedocs-flyout");
+            await elementUpdated(element);
+
+            // Addon default of 80% of global --readthedocs-font-size, default 16px


Where this "default 16px" comes from? We are defining these values in em, how they are converted into px at start up?

tests/flyout.test.html

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

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

humitos mentioned this pull request Apr 28, 2025

Links preview: add CSS variables to customize its look and feel #490

Open

humitos approved these changes Apr 29, 2025

View reviewed changes

agjohnson added 2 commits April 30, 2025 18:31

Default CSS to separate file

7a39c9d

Add and fix variables for search customization

78ab863

Fix lint issues with out of date pre-commit plugin

9d046a8

agjohnson added 2 commits May 7, 2025 09:52

Add basic unit test example for flyout styles

4b683a3

Just a basic font-size and color example, we can build on these as we go

Lint fix

b567494

agjohnson added 2 commits May 7, 2025 10:05

Merge branch 'main' into agj/merge/css-variable-root-default-2

f0f760f

Merge commit 'f0f760f' into agj/css-variable-root-default-2

3b252bd

agjohnson commented May 7, 2025

View reviewed changes

agjohnson requested a review from humitos May 7, 2025 17:09

agjohnson commented May 7, 2025

View reviewed changes

.pre-commit-config.yaml Show resolved Hide resolved

Undo temporary file changes for illustration/testing

73de0c8

humitos approved these changes May 12, 2025

View reviewed changes

Comment on test

82cd5c0

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

hgoel0 commented Apr 14, 2025

flying-sheep commented Apr 22, 2025 •

edited

Loading

agjohnson commented Apr 23, 2025 •

edited

Loading

humitos left a comment

agjohnson commented May 1, 2025 •

edited

Loading

agjohnson commented May 1, 2025 •

edited

Loading

humitos commented May 6, 2025

agjohnson commented May 7, 2025

agjohnson May 7, 2025

humitos May 12, 2025

agjohnson May 12, 2025

agjohnson commented May 7, 2025

humitos commented May 12, 2025

humitos commented May 12, 2025

humitos May 12, 2025

humitos May 12, 2025

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

hgoel0 commented Apr 14, 2025

flying-sheep commented Apr 22, 2025 • edited Loading

agjohnson commented Apr 23, 2025 • edited Loading

humitos left a comment

Choose a reason for hiding this comment

agjohnson commented May 1, 2025 • edited Loading

agjohnson commented May 1, 2025 • edited Loading

humitos commented May 6, 2025

agjohnson commented May 7, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson commented May 7, 2025

humitos commented May 12, 2025

humitos commented May 12, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

flying-sheep commented Apr 22, 2025 •

edited

Loading

agjohnson commented Apr 23, 2025 •

edited

Loading

agjohnson commented May 1, 2025 •

edited

Loading

agjohnson commented May 1, 2025 •

edited

Loading