From aa7fa2e0df75c24dbe5e2e9c2e7503ed07e670cd Mon Sep 17 00:00:00 2001
From: Rowan Cockett <rowanc1@gmail.com>
Date: Thu, 21 Mar 2024 14:17:50 -0600
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20Update=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/_toc.yml                       |  1 +
 docs/asides.md                      | 27 +++++++++++++++++++++------
 packages/myst-spec-ext/src/types.ts |  2 +-
 3 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/docs/_toc.yml b/docs/_toc.yml
index cb07cf438..a24adc971 100644
--- a/docs/_toc.yml
+++ b/docs/_toc.yml
@@ -23,6 +23,7 @@ parts:
       - file: exercises
       - file: blocks
       - file: diagrams
+      - file: asides
       - file: dropdowns-cards-and-tabs
       - file: glossaries-and-terms
   - caption: Executable Content
diff --git a/docs/asides.md b/docs/asides.md
index 870689616..6894286dd 100644
--- a/docs/asides.md
+++ b/docs/asides.md
@@ -1,16 +1,31 @@
 ---
-title: Asides
-description: Asides provide an easy way to represent content that is only indirectly related to the article's main content. 
+title: Asides, Margin Content, and Sidebars
+short_title: Asides and Margin Content
+description: Asides provide an easy way to represent content that is only indirectly related to the article's main content, such as in the sidebar or margin.
 ---
 
-## Asides
+Asides provide an easy way to represent content that is only indirectly related to the article's main content. Where supported, MyST will attempt to display an {myst:directive}`aside` _as close as possible_ but separately from the main article, such as in the side-margin.
 
-Asides provide an easy way to represent content that is only indirectly related to the article's main content. Where supported, MyST will attempt to display an `aside` _as close as possible_ but separately from the main article, such as in the side-margin. 
+```{aside}
+Here’s some margin content! It was created by using the {myst:directive}`margin` directive in a Markdown, we can include images:
+
+![](https://source.unsplash.com/random/400x75?sunset)
 
-````{myst}
-The main article contains main-article text!
+or any other sort of content!
+```
 
+````markdown
 ```{aside}
 This is an aside. It is not entirely relevant to the main article.
 ```
 ````
+
+You can also refer to this directive using {myst:directive}`margin` or {myst:directive}`sidebar`, which will have slightly different classes applied in the future.
+
+:::{warning} Experimental
+
+Many of the features on this page are experimental and may change at any time.
+
+These elements can conflict with the document outline when they are both competing for the margin space (see [#170](https://github.com/executablebooks/myst-theme/issues/170)).
+
+:::
diff --git a/packages/myst-spec-ext/src/types.ts b/packages/myst-spec-ext/src/types.ts
index 9667d7875..643e8f0f3 100644
--- a/packages/myst-spec-ext/src/types.ts
+++ b/packages/myst-spec-ext/src/types.ts
@@ -245,6 +245,6 @@ export type Output = Node & {
 
 export type Aside = Node & {
   type: 'aside';
-  kind?: 'sidebar';
+  kind?: 'sidebar' | 'margin';
   children?: (FlowContent | ListContent | PhrasingContent)[];
 };