Simplify user-story for CSS compilation with tools and frameworks (SCSS / Tailwind / etc)

[choldgraf]

Now that we support user stylesheets, it would be very useful if we could reduce the friction required for users to leverage CSS frameworks/tools in the creation of their style-sheets. This would allow authors to leverage modern technologies for CSS and design, and reduce the likelihood that authors need to create their own separate themes.

The two obvious examples that come to mind are:

• SCSS (because it is so common)
• Tailwind (because we already use Tailwind in the base theme)

Suggestions

We don't want this to increase the complexity of themes or the core infrastructure. With the present split between content server and web server, the simplest approach will be to build the stylesheet at content-build time, not at web-server time.

1. Add a hook to mystmd for build-plugins. There is some prior art for this, e.g. Docusaurus has a SASS plugin and recommends using it for SCSS and SASS. Unlike the existing transform plugins, this would operate only for web deployments, right at the end of the build.
2. Add a new stylesheet type to the MyST template options that invokes the Tailwind preprocessor at build-time. Unlike a build plugin, this abstracts away the fact that the compiler is being used under the hood, but ties us to tailwind.

Related: https://github.com/jupyter-book/mystmd/issues/1617

[agoose77]

The new style feature supported by MyST themes enables you to add custom CSS stylesheets to your MyST sites. You can use this feature in combination with tools like Tailwind to write your CSS styles inline in your documents using the power of CSS classes. In the future, we are looking to provide built-in support for Tailwind in our themes. But, for now you can bring-your-own-postprocessor (BYOP) and generate a custom stylesheet for the theme to use.

We have created a quickstart repository to demonstrate using Tailwind alongside a book with content. The README.md file outlines how to use the quickstart, but for completeness:

1. Install the dependencies of the styles package by running npm install in ./styles
2. Run the build command in ./styles via npm run build to generate styles/output.css.

To define your own CSS styles, you can modify styles/index.css, or use Tailwind-compatible CSS in your class names, e.g.

:::{figure} https://picsum.photos/id/817/512/128
:class: [&>*]:text-red-500

I am a figure
:::

In this example, the [&>*] variant selects any immediate child of the current element, and the text-red-500 utility sets its font color to red.

[!NOTE] Running the style build command npm run build invokes Tailwinds CLI tool to extract CSS class names from Markdown files in addition to building any styles defined in index.css. You should re-run this command after adding/removing CSS classes from your document(s).