Improve web documentation and document styles (#1628)

* Document HTML styles

* Update docs/website-style.md

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

* Update docs/website-style.md

* Update docs/blocks.md

* Update docs/website-style.md

---------

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

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.

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

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.

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.
+
+<div class="col-gutter-right" style="font-weight: bold;">Here's my div</div>
+
+Here's some <span class="col-gutter-right" style="font-weight:bold;">Span</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).