📖 Update docs

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

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)).
+
+:::

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)[];
 };