CSS Bundling & Theme Proposal

[Andrew Scholer]

I have been experimenting with different options for CSS bundling and reached a point where I see a few possible paths for what I PR. So I am reaching out for feedback/guidance.

For those who were not present at earlier discussions about using a program to bundle individual CSS files into fewer target files, the arguments for it are:

1. Running a CSS bundling tool makes it easier to have more modular CSS without requiring the browser to deal with an increasing number of CSS files. More modular CSS building blocks makes it easier to reuse styles across different targets without copy/paste.
2. It enables placing the CSS needed for a book into one consistently named file (theme.css) - making it easy to loaded in any context where the styling information is required. This would help in situations like when a Runestone assignment loads up individual exercises that have HTML rendered by PreTeXt but displays them outside of a PreTeXt book page - right now Runestone has no way of knowing what CSS to grab.
3. It is required for using SCSS or similar tools that make building/maintaining a CSS codebase easier.

It also represents a good time to consider streamlining the theme/color options for books. The goals of this would be to simplify the design space for people creating themes and thus simplify the development of things like dark mode support. That proposal is in this document:

https://docs.google.com/document/d/1ufTh3OZC3pMcTNVz5fED_BG2Z1gO2G0GwGJDo8tN7ro/edit?usp=sharing

Here are the options I have experimented with and could deliver as a PR:

1) A minimal solution that bundles into the same basic end files we have now. The only consolidation would be to turn all the TOC/Nav/Banner files into one option. This would not offer benefit #2 in the list above. It would preserve the author experience completely.

2) A solution that bundles all the files into a single theme.css appropriate for the book. It would deliver on the three benefits listed for bundling, but maintain all of the existing pain points around supporting arbitrary combinations of themes and colors. It would slightly simplify the author options (no more selecting navbar, toc, banner options to get a different theme).

3) A solution in line with what is in the google doc. Existing pub files relying on the default style or CRC and some color file would continue to generate a working CSS file that produced the same appearance. But there would be a new "traditional" layout (along with a new "wide" and possibly others) that move away from the author-specified color files in favor of something like primary & accent color. These themes would have dark mode support.

I personally am most excited about option 3. It is more work and the biggest change for authors going forward. But I think it would improve our ability to deliver future PreTeXt level design work and simplify things for an author who just wants a book that looks good and maybe uses their school color in a few key places. But, if there isn't an apetite for that, I'll PR option 2 or 1.

Please ask questions or share your thoughts.

I probably won't be at the Thursday drop in, but I should be at the next Tuesday one if anyone wants to connect live to talk about the proposal.

Andrew Scholer (he/him/his)

Computer Science Instructor/Program Chair

Chemeketa Community College

503.589.7649 

computerscience.chemeketa.edu/people/andrew-scholer/

[Rob Beezer]

Dear Andrew,

Thanks for your continued work to get the CSS on firm ground. If you like #3,
then so do I. But I hope we hear more from those who have done more of the work
on the CSS to-date.

Selfish questions:

1. I'm very careful about backward-compatibility, and it is a lot of tedious
work, but we have a variety of tricks at our disposal. I'll want to know
sometime about more details of how the publisher file will change. Drop-In is
fine, next Tuesday would work for me.

2. When a developer edits the schema, I generally create the four derivative
files and append that to their work. It is a service I provide since I know
those tools fairly well. If a developer makes a change to the CSS, whose
responsibility is the bundling? What does that process look like? What are th
tools and the steps? Does the HTML need to change, like we do for Runestone
CSS/JS currently?

Thanks,
Rob

On 7/24/24 07:40, Andrew Scholer wrote:
> I have been experimenting with different options for CSS bundling and reached a
> point where I see a few possible paths for what I PR. So I am reaching out for
> feedback/guidance.
>
> For those who were not present at earlier discussions about using a program to
> bundle individual CSS files into fewer target files, the arguments for it are:
>

> 1. Running a CSS bundling tool makes it easier to have more modular CSS without

> requiring the browser to deal with an increasing number of CSS files. More
> modular CSS building blocks makes it easier to reuse styles across different
> targets without copy/paste.

> 2. It enables placing the CSS needed for a book into one consistently named

> file (theme.css) - making it easy to loaded in any context where the styling
> information is required. This would help in situations like when a Runestone
> assignment loads up individual exercises that have HTML rendered by PreTeXt
> but displays them outside of a PreTeXt book page - right now Runestone has
> no way of knowing what CSS to grab.

> 3. It is required for using SCSS or similar tools that make

> building/maintaining a CSS codebase easier.
>
>
> It also represents a good time to consider streamlining the theme/color options
> for books. The goals of this would be to simplify the design space for people
> creating themes and thus simplify the development of things like dark mode
> support. That proposal is in this document:

> https://docs.google.com/document/d/1ufTh3OZC3pMcTNVz5fED_BG2Z1gO2G0GwGJDo8tN7ro/edit?usp=sharing <https://docs.google.com/document/d/1ufTh3OZC3pMcTNVz5fED_BG2Z1gO2G0GwGJDo8tN7ro/edit?usp=sharing>

> <http://computerscience.chemeketa.edu/people/andrew-scholer/>
>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to pretext-dev...@googlegroups.com
> <mailto:pretext-dev...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pretext-dev/CACm44N9BkD0rPDsWT4Wrz2mmotVnXe56rj20Z%2B8jTZxGgtWZ3Q%40mail.gmail.com <https://groups.google.com/d/msgid/pretext-dev/CACm44N9BkD0rPDsWT4Wrz2mmotVnXe56rj20Z%2B8jTZxGgtWZ3Q%40mail.gmail.com?utm_medium=email&utm_source=footer>.

[Andrew Scholer]

Good questions.

1. 

Sounds good. It would be fairly easy to produce more "legacy" bundles that support existing pubfiles using style= crc or oscan-levin or wide with a warning. It just means shipping extra pre-computed bundles.

2. 

As of now, the bundling code is in scripts/cssbundler. Producing bundles requires having node installed, doing a one time `npm install`, and then doing `npm run build` in that directory (the underlying tool that node is using is currently esbuild). That produces the various bundles into css/dist. To develop CSS, someone would need to use those tools to test out changes.

Storing bundles in the git repo is the kind of thing that all git advice will tell you to avoid. But if they are tracked by git, changing and then testing the CSS would update the relevant bundles. Git status would show them as changed and they could be included in a PR. A PR reviewer would not need to rebuild the bundles.

These files are going to be much more dynamic than the other precomputed assets that are stored for the examples. I think it is worth talking about options for doing something more like what is done with the Runestone assets... The bundles could be left out of the repository, built automatically on push as a release to some known location, and retrieved at build time (if not already present or out of date) by the devscript.

As to the HTML modification, I assume you mean grabbing the right name of the Runestone bundle at build time. The need for that depends on how people are serving their files and how much you want to protect them from their server. The reason for producing something like theme.2jh3423h421d.css instead of theme.css is to make sure that it absolutely will not be cached. If we always produce "theme.css" and reference that from a book, and a reader does not hard refresh their page, their browser may continue to use the old theme.css even if the file is changed. Manual cache busting is considered less essential than it once was. In the old days the tendency was to aggressively cache, requiring developers to manually bust the cache. It is common now to have shorter cache durations, encouraging the client to check back more frequently to see if there is a modified file. For example, on github pages, a static asset are only cached for 10 minutes - meaning the longest a reader might be served the old CSS would be that duration. So... if you want to protect authors from situations where they might throw a book on a server that some sysadmin has configured to request that clients cache CSS for 100 years, yes we need to produce cache-busting names (or the author will need to tell readers "hit Ctrl-F5" frequently). And there would need to be a system for Runetone to find out the cachebusting name in use for a book. If you willing to not protect authors from their servers in that way, we could always just have "theme.css" in the HTML and occasionally a user's CSS would be a few minutes out of date.

Andrew Scholer (he/him/his)

Computer Science Instructor/Program Chair

Chemeketa Community College

503.589.7649 

computerscience.chemeketa.edu/people/andrew-scholer/

To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAwNC5iZWV6ZXI.1721919138%40quikprotect.