bad syntax highlighting with a11y highlighting style and JS disabled

[gordonwoodhull]

Similar to #12399, the a11y highlighting style also has stylesheet bleed problems when JS is disabled.

I remembered that we will need to do light, dark, light stylesheets for syntax highlighting in NoJS, just as we are doing for main stylesheets in #12514

So I looked at our deployed test, and sure enough, there is bad syntax highlighting in light mode with JS disabled:

https://gordonwoodhull.github.io/quarto-web-safari-bugless/docs/computations/python.html

The a11y dark style rule for "imports" code span.im has higher specificity than the light style, which does not define this one.

[gordonwoodhull]

It looks like the code span.im rule is not necessary here, since code span already has that color in the dark theme.

Do we have a comprehensive syntax highlighting example that exercises all highlight classes? I'd like to look at both of these issues in a more thorough way, and maybe add more automated tests for them.

[cderv]

Do we have a comprehensive syntax highlighting example that exercises all highlight classes?

For that, you could see if one of the .theme files has a value for all keywords. The classes are derived from those keywords

quarto-cli/src/quarto-core/text-highlighting.ts

Lines 147 to 179 in 6bac7fb

	export const kAbbrevs: Record<string, string> = {
	"Keyword": "kw",
	"DataType": "dt",
	"DecVal": "dv",
	"BaseN": "bn",
	"Float": "fl",
	"Char": "ch",
	"String": "st",
	"Comment": "co",
	"Other": "ot",
	"Alert": "al",
	"Function": "fu",
	"RegionMarker": "re",
	"Error": "er",
	"Constant": "cn",
	"SpecialChar": "sc",
	"VerbatimString": "vs",
	"SpecialString": "ss",
	"Import": "im",
	"Documentation": "do",
	"Annotation": "an",
	"CommentVar": "cv",
	"Variable": "va",
	"ControlFlow": "cf",
	"Operator": "op",
	"BuiltIn": "bu",
	"Extension": "ex",
	"Preprocessor": "pp",
	"Attribute": "at",
	"Information": "in",
	"Warning": "wa",
	"Normal": "",
	};

We are doing in Quarto what is supposed to be done by Pandoc directly. So we recreate the classes in SCSS based on theme file content.

If no theme has all, the best way to test this would be to create a dummy theme file with all the keywords filled (no text-color: null) and see the rendering behavior with it.

the a11y highlighting style also has stylesheet bleed problems when JS is disabled.

If this is only a problem with this theme file, we could modify it. I believe we own the a11y theme file. Some are from Pandoc's bundle directly, but others are provided by us in Quarto.

However, I think you will have the problem with any other theme file that defines "text-color": null in its light version and not null in its dark version.

To my knowledge, syntax highlighting themes are not designed to be layered one onto the other. So I am not surprised that if you do light after dark, some dark rules could leak.

TBH, I am still puzzled by our desire to get noJS working for syntax highlighting by playing with CSS layering. We are trying to solve a problem that will make the "normal" behavior more complex.

My take on this that I did not have time to share the other day:

• No JS means that no javascript is supposed to be working, so there will be no dark light switch possible in the HTML. This means we could write only the CSS for the theme (light or dark) chosen first by the document's author.

• If we do that for all cases (JS or noJS), it seems we could leverage the JS presence now to add the other theme (dark or light) dynamically when the webpage loads. This other theme will only be activated when the theme switch on the page is changed.

However, you may have tried that already. And this could still not solve all flashing or similar. 🤷

[mcanouil]

FWIW, the bootstrap approach to color mode: https://getbootstrap.com/docs/5.3/customize/color-modes/#javascript

[gordonwoodhull]

To my knowledge, syntax highlighting themes are not designed to be layered one onto the other. So I am not surprised that if you do light after dark, some dark rules could leak.

They are designed, or at least time-tested, to allow layering light + dark, because that is the way they have always been applied. I concede that they are not designed for being layered dark + light! But this seems to be the best compromise for making light mode pages still have basic legibility with NoJS.

add the other theme (dark or light) dynamically when the webpage loads.

Yeah, this is one of the things that causes flashing.

It makes sense, if you think about it. You are already inside the page, and JS decides it needs another stylesheet. So there will need to be a fetch.

What should the browser do then, wait for the fetch before displaying anything? But that might take a long time.

So instead it starts showing the next content and asynchronously fetches the CSS, then does a "reflow" in order to add the stylesheet when it arrives, before the content. (I think reflow is the relevant term; it doesn't seem to be formally defined.)

In my testing, I found that I was unable to add or reorder stylesheets during loading page load, without causing flashing. I could only disable already-loaded stylesheets.

So, for now, we are stuck with a design that loads all stylesheets and then (in JS) disables some of them.

IMO if we wanted to fix all flashing and stylesheet issues for good, we would do away with any swapping or disabling of stylesheets and just use one stylesheet with CSS rules that are enabled based on color scheme.

It's overall much simpler, with no moving parts. But it would be a big refactor and would be likely to break things. I didn't have the knowledge or the time to do this in 1.7.

FWIW, the bootstrap approach to color mode

The bootstrap approach is very nice! It allows things like not having a toggle and just following the prefers-color-scheme media query. (Which is what I think most people will want in 5-10 years.)

It is the "one stylesheet, color scheme–enabled rules" approach. They metaprogram it with SASS mixins.

They don't offer a UI toggle, but they give you the code @mcanouil linked above, equivalent to our quarto-html-before-body.ejs — 80 lines to our ~170.

I think we should consider using their system, but we'd have to figure out if we can bring over users' existing (dark) stylesheets and what else this would break. Worth experimenting, but I wouldn't commit to any timeframe.

[cderv]

Thanks a lot for the clarification. It helps me understand. I guess I did not get all the loading / fetching things in orders.

The one stylesheet seems the right way at the end - SCSS allows us to make that not that complicated to maintain and create I guess.

Bootstrap 5.3.0 brought it, but we never tried to support it or see the impact of supporting it. It relates to

• Make Bootswatch paired light and dark themes available #6741 and associated discussion Make Bootswatch paired light and dark themes available #6740

Quarto has started before Boostrap has this, so obviously it needs some work, but it seems for the best, if we can do something.