Section 49.2 Building the CSS
The distrubuted CSS files are build from SCSS (or “Sass”) source files. SCSS is a superset of CSS that adds variables, nesting, functions, and a module system (
@use) for splitting styles across files. This source is built into ordinary CSS for use by the browser.
Plain CSS is valid SCSS, so for the most part, adding styles to elements just involves writing normal CSS. The extra features of SCSS are only needed when you want to differentiate the CSS output for different themes or integrate with the color palettes. The Sass basics guide is a good resource for learning about SCSS features.
The build script is
script/cssbuilder, run with node. In normal use you never invoke it directly—the PreTeXt script and the CLI build whatever theme a document needs. The one-time setup is to install node and run npm install once in script/cssbuilder (the CLI does even this for you). See Appendix F for node and npm. Once that is done, you can build all of the CSS targets from the cssbuilder directory with:
script/cssbuilder$ npm run build
When working on the CSS for a feature, you will likely not want to build all the theme files and then have to rebuild your test book. Instead, you will likely want to update just the CSS directly in your book so you that you can examine styling updates without rebuilding the entire project or moving files around. The simplest way is to use the PreTeXt script’s
-c theme flag to rebuild only the theme (See Chapter 47) directly to your book.
For finer control over which theme is built (to rapidly check different themes), or to have the CSS automatically rebuild when you change the source, you can run the build script directly with
node. From the script/cssbuilder directory, do:
script/cssbuilder$ npm run build -- -t theme-default-modern -o path_to_yourbook/_static/pretext/css -w
The
-- is required so the flags reach the script rather than npm. Useful flags: -t (one target; -l lists them), -o (output directory), -w (watch and rebuild on changes), and -c (a JSON string of options and variables, the same ones a publisher sets, for trying colors and options). Run npm run build -- -h for the full list; details are in script/cssbuilder/README.md.
