💇 Add documentation on site.options.style (#1873)

Co-authored-by: Rowan Cockett <rowanc1@gmail.com>

Author: agoose77

.changeset/spotty-planets-fetch.md

@@ -0,0 +1,5 @@
+---
+"myst-transforms": patch
+---
+
+Add support for `class` in block data

docs/deployment.md

@@ -23,7 +23,7 @@ The high-level differences between these approaches are outlined in [](#deployme
 :::{note} MyST was designed to be deployed as an application
 Deploying MyST as an application has many benefits. For example, [performance enhancements](./accessibility-and-performance.md) (like pre-fetching for instant page-transitions, loading indicators, and smaller network payloads) and easier upgrades as new MyST versions are released.
 
-The [default themes](website-templates.md#themes-bundled-with-myst) for MyST are designed to be MyST applications rather than static sites, but the core functionality is equally shared between the two options.
+The [default themes](#default-web-themes) for MyST are designed to be MyST applications rather than static sites, but the core functionality is equally shared between the two options.
 :::
 
 % - Static deployments are MPA (each page own HTML document), SSG (rendered ahead of time)

docs/myst.yml

@@ -167,3 +167,5 @@ site:
   title: MyST Markdown Guide
   domains:
     - mystmd-guide.curve.space
+  options:
+    style: public/style.css

docs/public/style.css

@@ -0,0 +1,5 @@
+.text-gradient em {
+  background: -webkit-linear-gradient(#eee, #333);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+}

docs/website-style.md

@@ -11,83 +11,67 @@ We're still building out custom CSS functionality with the MyST engine.
 Follow and comment on the issues linked below to help us improve it!
 :::
 
-## Use content blocks
+## Defining a Style Sheet
 
-:::{warning} CSS class support is very limited
-Currently, you can only use CSS classes that are pre-loaded by MyST from Tailwind CSS, or defined in the HTML theme (see below for examples of both).
-See these issues to track some of this:
+The [default MyST website themes](#default-web-themes) support bundling a custom [style-sheet](https://en.wikipedia.org/wiki/CSS). This can be used to introduce custom CSS styling to your website. To include a custom CSS file as part of your website build, you can define the @template-site-myst-book-theme-style option, e.g.
 
-- Defining your own CSS classes: https://github.com/jupyter-book/mystmd/issues/857
-- Load extra Tailwind CSS classes when they're used on a page: https://github.com/jupyter-book/mystmd/issues/1617
+```{code} yaml
+:filename: myst.yml
+:linenos:
+:emphasize-lines: 3
+site:
+  options:
+    style: ./my-style.css
+```
+
+For example, the style-sheet could contain styling for `em` elements nested below a particular `text-gradient` class:
+
+:::{literalinclude} public/style.css
 :::
 
+## Adding CSS Classes
+
+The intended way to apply custom styling to your MyST website is to use CSS classes to connect your content to the style sheet. There are several ways to do this.
+
+### Use content blocks
+
 [Content blocks](../blocks.md) allow you to attach arbitrary metadata to chunks of content.
 You can attach one or more CSS classes by defining a `class` attribute for a block.
 For example the following:
 
-```md
-+++ {"class": "col-gutter-right"}
-Right-styled
+```{myst}
++++ {"class": "text-gradient"}
+This is _emphasized_. This is not emphasized.
 
 +++
 
-Normal-styled
+This is not emphasized.
 ```
 
-Results in:
-
-+++ {"class": "col-gutter-right"}
-Right-styled
-
-+++
-
-Normal-styled
-
-## Use `div` and `span` elements
+### Use `div` and `span` elements
 
 You can attach classes directly to [`div` and `span` elements](#div-and-span).
 
 {myst:directive}`div` and {myst:role}`span` are analogous to their HTML counterparts. Unlike their directive/role, the HTML elements can also be given `style` options, e.g.
 
-<div class="col-gutter-right" style="font-weight: bold;">Here's my div</div>
+```{myst}
+<div class="text-gradient" style="font-weight: bold;">Here's my <em>div</em></div>
 
-Here's some <span class="col-gutter-right" style="font-weight:bold;">Span</span> content
-
-## Add CSS classes to directives
+Here's some <span class="text-gradient" style="font-weight:bold;">span <em>styled</em></span> content
+```
 
-:::{note} Not all directives support the `:class:` option
-If you wish to attach classes to a directive that doesn't seem to support it, please [open an issue](https://github.com/jupyter-book/mystmd/issues)
-:::
+### Add CSS classes to directives
 
 Many directives and content blocks have a `:class:` option that can be used to add arbitrary CSS classes.
 For example, below we add a CSS class to an admonition directive to snap it to the right:
 
-````md
+````{myst}
 ```{note}
-:class: col-gutter-right
-I'm on the right!
+:class: text-gradient
+I'm _very stylish_.
 ```
 ````
 
-```{note}
-:class: col-gutter-right
-I'm on the right!
-```
-
-## Use the HTML theme grid system classes to position content
-
-The HTML themes come with [a grid system of CSS classes](https://jupyter-book.github.io/myst-theme/?path=/docs/components-grid-system--docs).
-You can use these to position content according to the link above.
-
-## Use Tailwind CSS classes
-
-:::{note} Provide feedback
-This issue tracks loading extra Tailwind CSS classes when they're used on a page:
-
-- https://github.com/jupyter-book/mystmd/issues/1617
-:::
+## Built-in CSS Classes
 
-You can use any [Tailwind CSS class](https://tailwindcss.com/docs/installation) that's loaded on a page to style your content.
-See the Tailwind documentation for examples of how to do this.
-If a class seems to have no effect, it is likely not loaded on the page by MyST.
-Currently, it's not possible to customize which classes are included on a page (see above for an issue tracking this).
+The HTML themes come with [a grid system of CSS classes](https://jupyter-book.github.io/myst-theme/?path=/docs/components-grid-system--docs), which can be used out-of-the-box to position content.

docs/website-templates.md

@@ -11,6 +11,8 @@ They are defined via the same templating system used for [static document export
 For the remainder of this page, assume that "theme" and "template" mean the same thing.
 :::
 
+(default-web-themes)=
+
 ## Themes bundled with MyST
 
 There are two templates for MyST websites, a `book-theme`, which is the default and is based loosely on Jupyter Book and an `article-theme` that is designed for scientific documents with supporting notebooks. The documentation for this site uses the `book-theme`. For a demonstration of the `article-theme`, you can see [an article on finite volume](https://simpeg.xyz/tle-finitevolume).

packages/myst-cli/src/build/html/index.ts

@@ -89,7 +89,8 @@ function rewriteAssetsFolder(directory: string, baseurl?: string): void {
     const data = fs.readFileSync(file).toString();
     const modified = data
       .replace(new RegExp(`\\/${ASSETS_FOLDER}\\/`, 'g'), `${baseurl || ''}/build/`)
-      .replace('href="/favicon.ico"', `href="${baseurl || ''}/favicon.ico"`);
+      .replace('href="/favicon.ico"', `href="${baseurl || ''}/favicon.ico"`)
+      .replace('href="/myst-theme.css"', `href="${baseurl || ''}/myst-theme.css"`);
     fs.writeFileSync(file, modified);
   });
 }