DOCS: improving markdown tagging information (#1042)

docs/advanced/advanced.md

@@ -77,6 +77,8 @@ in the metadata of your cells. This allows you to do things like
 {doc}`automatically hide code cells <../interactive/hiding>`) as well as
 {ref}`add interactive widgets to cells <launch/thebelab>`.
 
+### Adding tags using notebook interfaces
+
 There are two straightforward ways to add metadata to cells:
 
 1. **Use the Jupyter Notebook cell tag editor**. The Jupyter Notebook ships with a
@@ -105,7 +107,20 @@ There are three levels of metadata:
 
 ![NB Metadata GIF](../images/metadata_edit.*)
 
-### Add tags to notebook cells based on their content
+### Add tags using MyST Markdown notebooks
+
+If you're writing notebooks with MyST Markdown, then you can add tags to each code cell when you write the `{code-cell}` block. For example, below we:
+
+````
+```{code-cell}
+:tags: [tag1,tag2,tag3]
+print("some code")
+```
+````
+
+Will create a code cell with those three tags attached to it. For more information about MyST Markdown notebooks, see [](../file-types/myst-notebooks.md).
+
+### Add tags using Python code
 
 Sometimes you'd like to quickly scan through a notebook's cells in order to
 add tags based on the content of the cell. For example, you might want to

docs/content/content-blocks.md

@@ -619,3 +619,25 @@ at the bottom of this page.
 [^mynote2]: And the text of my second note.
             Note that
             [you can include Markdown footnote definitions](https://executablebooks.org).
+
+(custom-div-blocks)=
+## Custom `<div>` blocks
+
+You can add custom `div` blocks along with whatever classes you'd like using
+the `{div}` directive. The `{div}` directive will wrap everything inside in a single `<div>` with the classes you provide. For example:
+
+````md
+```{div} my-class
+**Some content.**
+```
+````
+
+Will result in the following HTML when your book is built:
+
+```html
+<div class="my-class">
+  <strong>Some content.</strong>
+</div>
+```
+
+This can be useful if you'd like to style your book with [custom CSS or JavaScript](custom-assets).

docs/content/layout.md

@@ -170,15 +170,14 @@ for ii in range(40):
     print(f"this is output line {ii}")
 ```
 
-## Wide-format content
+## Full-width content
 
-Sometimes, you'd like to use **all** of the horizontal space available to you. This allows
-you to highlight particular ideas, visualizations, etc.
+Sometimes, you'd like to use **all** of the horizontal space available to you.
+This allows you to highlight particular ideas, visualizations, etc.
 
-In Jupyter Book, you can specify that the outputs of a cell (if it's a code cell) or the entire
-cell (if it's a Markdown cell) should take up all of
-the horizontal space (including the margin to the right) using the
-following cell metadata tag:
+### Full-width code cells
+
+You can specify that a code cell's inputs and/or outputs should take up all of the horizontal space (including the margin to the right) using the following cell metadata tag:
 
 ```json
 {
@@ -188,7 +187,9 @@ following cell metadata tag:
 }
 ```
 
-This works equally well on Markdown cells and on code cells.
+```{seealso}
+For tips on how to add cell metadata to your notebooks, see [](jupyter-cell-tags).
+```
 
 For example, let's take a look at the figure in the margin above in a cell with `full-width` set. We'll tell Matplotlib
 to make it a bit wider so we can take advantage of the extra space!
@@ -199,15 +200,53 @@ to make it a bit wider so we can take advantage of the extra space!
 make_fig(figsize=(20, 5))
 ```
 
-This can work with Markdown cells as well. For example, we'll make the following warning block `full-width` so that
-it draws more attention to it:
+### Full-width markdown content
+
+If you'd like to make your markdown content full-width, you cannot do so via cell tags.
+Instead, you have a few options:
+
+1. **Use the `{div}` directive with a `full-width` class.**. Any content with a `full-width` class will take up the full width of the screen. For example, the following code:
+
+   `````
+   ````{div} full-width
+   ```{note}
+   Here's a note that will take the full width
+   ```
+   ````
+   `````
+
+   results in:
+
+   ````{div} full-width
+   ```{note}
+   Here's a note that will take the full width
+   ```
+   ````
+
+   For more information on `<div>` blocks, see [](custom-div-blocks).
+2. **Add a `full-width` class to directives that support classes**. Many directives allow you to directly add a CSS class to them.
+
+   For example, the `{note}` directive above allows for this:
+
+   ````
+   ```{note}
+   :class: full-width
+   Here's a note that will take the full width
+   ```
+   ````
+
+   results in:
+
+   ```{note}
+   :class: full-width
+   Here's a note that will take the full width
+   ```
 
-+++ {"tags": ["full-width"]}
+   Check the documentation of the directive to see if it supports adding your own classes, or use the `{div}` directive as described above.
 
-```{admonition} **Be careful about mixing popouts and full-width content**.
-:class: full-width
+```{admonition} **Mixing margins and full-width content**
+:class: warning, full-width
 
-Sometimes these can conflict
-with one another in visual space. You should use them relatively sparingly in order
-for them to have their full effect of highlighting information.
+Be careful when mixing margins and full-width content.
+Sometimes these can conflict with one another in visual space. You should use them relatively sparingly in order for them to have their full effect of highlighting information.
 ```