From a34346f63038ebfbb1b3da8482cecac98e5ea448 Mon Sep 17 00:00:00 2001
From: Angus Hollands <goosey15@gmail.com>
Date: Tue, 25 Feb 2025 11:47:31 +0000
Subject: [PATCH 1/8] docs: add docs on styling with CSS

---
 docs/myst.yml         |  2 +
 docs/public/style.css |  5 +++
 docs/website-style.md | 89 ++++++++++++++++++++-----------------------
 3 files changed, 48 insertions(+), 48 deletions(-)
 create mode 100644 docs/public/style.css

diff --git a/docs/myst.yml b/docs/myst.yml
index cf10ac3d71..1f41b43614 100644
--- a/docs/myst.yml
+++ b/docs/myst.yml
@@ -167,3 +167,5 @@ site:
   title: MyST Markdown Guide
   domains:
     - mystmd-guide.curve.space
+  options:
+    style: public/style.css
diff --git a/docs/public/style.css b/docs/public/style.css
new file mode 100644
index 0000000000..7766fa1f84
--- /dev/null
+++ b/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;
+}
diff --git a/docs/website-style.md b/docs/website-style.md
index defb7ddaa8..db5f9de9ed 100644
--- a/docs/website-style.md
+++ b/docs/website-style.md
@@ -11,49 +11,61 @@ 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:
+Default MyST themes like the book theme and article theme 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
+```
 
-[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:
+For example, the style-sheet could contain styling for `em` elements nested below a particular `text-gradient` class:
 
-```md
-+++ {"class": "col-gutter-right"}
-Right-styled
+```css
+.text-gradient em {
+  background: -webkit-linear-gradient(#eee, #333);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+}
+```
 
-+++
+## Adding CSS Classes
 
-Normal-styled
-```
+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
 
-Results in:
+[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:
 
-+++ {"class": "col-gutter-right"}
-Right-styled
+```{myst}
++++ {"class": "text-gradient"}
+This is _emphasized_. This is not emphasized.
 
 +++
 
-Normal-styled
+This is not emphasized.
+```
 
-## 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
+Here's some <span class="text-gradient" style="font-weight:bold;">span <em>styled</em></span> content
+```
 
-## Add CSS classes to directives
+### Add CSS classes to directives
 
 :::{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)
@@ -62,32 +74,13 @@ If you wish to attach classes to a directive that doesn't seem to support it, pl
 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.

From 4504f167f3a02f55c8f1c221498a4d9d8c759eb0 Mon Sep 17 00:00:00 2001
From: Angus Hollands <goosey15@gmail.com>
Date: Tue, 25 Feb 2025 12:39:47 +0000
Subject: [PATCH 2/8] feat: copy class from block

---
 packages/myst-transforms/src/blocks.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/myst-transforms/src/blocks.ts b/packages/myst-transforms/src/blocks.ts
index 4b22503103..8fbbb436a1 100644
--- a/packages/myst-transforms/src/blocks.ts
+++ b/packages/myst-transforms/src/blocks.ts
@@ -51,6 +51,11 @@ export function blockMetadataTransform(mdast: GenericParent, file: VFile) {
         });
       }
     }
+    const className = block.data?.class;
+    if (typeof className === 'string') {
+      block.class = className;
+      delete block.data.class;
+    }
     const label = block.data?.label ?? block.data?.id;
     if (typeof label === 'string') {
       const normalized = normalizeLabel(label);

From c054300824206451a7248f1845b8808e15cf07b9 Mon Sep 17 00:00:00 2001
From: Angus Hollands <goosey15@gmail.com>
Date: Tue, 25 Feb 2025 12:40:19 +0000
Subject: [PATCH 3/8] docs: drop note -- no longer applies

---
 docs/website-style.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/docs/website-style.md b/docs/website-style.md
index db5f9de9ed..8ffcd01da3 100644
--- a/docs/website-style.md
+++ b/docs/website-style.md
@@ -67,10 +67,6 @@ Here's some <span class="text-gradient" style="font-weight:bold;">span <em>style
 
 ### Add CSS classes to directives
 
-:::{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)
-:::
-
 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:
 

From 1c75706c824f00d544acf5bd343def93b1e1f0a4 Mon Sep 17 00:00:00 2001
From: Angus Hollands <goosey15@gmail.com>
Date: Tue, 25 Feb 2025 13:03:45 +0000
Subject: [PATCH 4/8] chore: add changeset

---
 .changeset/spotty-planets-fetch.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/spotty-planets-fetch.md

diff --git a/.changeset/spotty-planets-fetch.md b/.changeset/spotty-planets-fetch.md
new file mode 100644
index 0000000000..26674b92a9
--- /dev/null
+++ b/.changeset/spotty-planets-fetch.md
@@ -0,0 +1,5 @@
+---
+"myst-transforms": patch
+---
+
+Add support for `class` in block data

From 332d320e1695b4c50062b2d3c694b06b71d42e95 Mon Sep 17 00:00:00 2001
From: Angus Hollands <goosey15@gmail.com>
Date: Tue, 25 Feb 2025 16:15:47 +0000
Subject: [PATCH 5/8] docs: link to default themes

---
 docs/deployment.md        | 2 +-
 docs/website-style.md     | 2 +-
 docs/website-templates.md | 2 ++
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index 45ca702b07..7b3978b3c8 100644
--- a/docs/deployment.md
+++ b/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)
diff --git a/docs/website-style.md b/docs/website-style.md
index 8ffcd01da3..93cfd23cac 100644
--- a/docs/website-style.md
+++ b/docs/website-style.md
@@ -13,7 +13,7 @@ Follow and comment on the issues linked below to help us improve it!
 
 ## Defining a Style Sheet
 
-Default MyST themes like the book theme and article theme 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.
+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.
 
 ```{code} yaml
 :filename: myst.yml
diff --git a/docs/website-templates.md b/docs/website-templates.md
index a50b913ef8..c940dbfad8 100644
--- a/docs/website-templates.md
+++ b/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).

From bf23f6c9d12d1934b19652b25047116e4dee53d5 Mon Sep 17 00:00:00 2001
From: Angus Hollands <goosey15@gmail.com>
Date: Thu, 27 Feb 2025 12:58:43 +0000
Subject: [PATCH 6/8] fix: revert changes to block

---
 packages/myst-transforms/src/blocks.ts | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/packages/myst-transforms/src/blocks.ts b/packages/myst-transforms/src/blocks.ts
index 8fbbb436a1..4b22503103 100644
--- a/packages/myst-transforms/src/blocks.ts
+++ b/packages/myst-transforms/src/blocks.ts
@@ -51,11 +51,6 @@ export function blockMetadataTransform(mdast: GenericParent, file: VFile) {
         });
       }
     }
-    const className = block.data?.class;
-    if (typeof className === 'string') {
-      block.class = className;
-      delete block.data.class;
-    }
     const label = block.data?.label ?? block.data?.id;
     if (typeof label === 'string') {
       const normalized = normalizeLabel(label);

From 78a55c84e89e3219aeda30a1e4a6ae724f53f8a9 Mon Sep 17 00:00:00 2001
From: Rowan Cockett <rowanc1@gmail.com>
Date: Thu, 27 Feb 2025 08:58:55 -0700
Subject: [PATCH 7/8] use literal include

---
 docs/website-style.md | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/docs/website-style.md b/docs/website-style.md
index 93cfd23cac..001298698d 100644
--- a/docs/website-style.md
+++ b/docs/website-style.md
@@ -26,13 +26,8 @@ site:
 
 For example, the style-sheet could contain styling for `em` elements nested below a particular `text-gradient` class:
 
-```css
-.text-gradient em {
-  background: -webkit-linear-gradient(#eee, #333);
-  -webkit-background-clip: text;
-  -webkit-text-fill-color: transparent;
-}
-```
+:::{literalinclude} public/style.css
+:::
 
 ## Adding CSS Classes
 

From 2f2eae0a2b8dd29c6080b57c6f423657da9c20d4 Mon Sep 17 00:00:00 2001
From: Rowan Cockett <rowanc1@gmail.com>
Date: Thu, 27 Feb 2025 09:00:43 -0700
Subject: [PATCH 8/8] handle asset folder change.

---
 packages/myst-cli/src/build/html/index.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/myst-cli/src/build/html/index.ts b/packages/myst-cli/src/build/html/index.ts
index 9daece8437..a30f5e77da 100644
--- a/packages/myst-cli/src/build/html/index.ts
+++ b/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);
   });
 }