diff --git a/docs/blocks.md b/docs/blocks.md
index 3494652ce..460babeb7 100644
--- a/docs/blocks.md
+++ b/docs/blocks.md
@@ -6,7 +6,9 @@ description: Blocks provide structural division in a MyST document using `+++`.
## Blocks
-`Blocks` provide a structural division of MyST documents using `+++`. These correspond, for example, to separate cells in a Jupyter Notebook. There can be optional metadata associated with the block, such as "tags", "parts" or other identifiers.
+`Blocks` provide a structural division of MyST documents using `+++`.
+There can be optional metadata associated with the block, such as "tags", "parts" or other identifiers.
+This is used to attach attributes to chunks of content, or to break your page into cells for a Jupyter Notebook.
```{myst}
+++ {"cell": "one"}
@@ -19,6 +21,11 @@ cell 2
To identify a [part of a document](./document-parts.md), like an abstract, use `+++ { "part": "abstract" }`, this will allow tools like the [](./creating-pdf-documents.md) to be created with the appropriate parts of information.
```
+### Document parts
+
+You can use blocks to split your document into parts.
+See [](#parts:blocks) for more information.
+
### Page Breaks
You may use `block` metadata to insert page breaks into your PDF or docx export with `+++ { "page-break": true }`. This will have no impact on your MyST site build nor other static exports that disregard "pages" (e.g. JATS).
@@ -27,6 +34,31 @@ You may use `block` metadata to insert page breaks into your PDF or docx export
You may also use `"new-page"` instead of `"page-break"`. This distinction only matters for $\LaTeX$ where `\newpage` and `\pagebreak` will be used, respectively.
```
+### Add classes to blocks
+
+You may attach CSS classes to blocks in order to control their behavior.
+The default MyST
+
+(div-and-span)=
+### `div` and `span` elements
+
+You can add `div` and `span` elements to serve a similar purpose.
+Any classes and content that you add will be attached to the AST of your document.
+
+For example, here's a div that uses [the HTML theme grid classes](https://jupyter-book.github.io/myst-theme/?path=/docs/components-grid-system--docs) to snap a div to the right:
+
+```markdown
+:::{div}
+:class: col-gutter-right
+I'm off to the right!
+:::
+```
+
+:::{div}
+:class: col-gutter-right
+I'm off to the right!
+:::
+
## Comments
You may add comments by putting the `%` character at the beginning of a line. This will prevent the line from being shown in the output document.
diff --git a/docs/images/website-layout.excalidraw.svg b/docs/images/website-layout.excalidraw.svg
index 5c4694ad6..a50911d45 100644
--- a/docs/images/website-layout.excalidraw.svg
+++ b/docs/images/website-layout.excalidraw.svg
@@ -1,13 +1,10 @@
\ No newline at end of file
+ PrimarySidebarContentWindowSecondarySidebarWebsite HeaderWebsiteFooterTitle Block(TOC, table of contents)Document OutlineFooter Links
\ No newline at end of file
diff --git a/docs/myst.yml b/docs/myst.yml
index 6af88f2e9..6b14e0140 100644
--- a/docs/myst.yml
+++ b/docs/myst.yml
@@ -115,6 +115,7 @@ project:
- file: website-metadata.md
# - file: themes-and-extensions.md
- file: seo-and-social.md
+ - file: website-style.md
- file: accessibility-and-performance.md
# - file: search.md
- file: analytics.md
diff --git a/docs/quickstart-jupyter-lab-myst.md b/docs/quickstart-jupyter-lab-myst.md
index 80d72468f..0aba743fe 100644
--- a/docs/quickstart-jupyter-lab-myst.md
+++ b/docs/quickstart-jupyter-lab-myst.md
@@ -94,6 +94,7 @@ More Coming Soon™
---
+(inline-expressions)=
## Inline Expressions
JupyterLab MyST allows you to create and evaluate inline expressions using the {myst:role}`eval` role.
diff --git a/docs/website-style.md b/docs/website-style.md
new file mode 100644
index 000000000..defb7ddaa
--- /dev/null
+++ b/docs/website-style.md
@@ -0,0 +1,93 @@
+---
+title: Styles and CSS Classes
+description: How to customize the look and feel of your website with CSS.
+---
+
+MyST has basic support for styling your content with CSS.
+This page describes some common ways to do so.
+
+:::{caution} This is still a work in progress
+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
+
+:::{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:
+
+- 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
+:::
+
+[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
+
++++
+
+Normal-styled
+```
+
+Results in:
+
++++ {"class": "col-gutter-right"}
+Right-styled
+
++++
+
+Normal-styled
+
+## 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.
+
+
Here's my div
+
+Here's some Span content
+
+## 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:
+
+````md
+```{note}
+:class: col-gutter-right
+I'm on the right!
+```
+````
+
+```{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
+:::
+
+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).