💅 🖼️ Add topic directive (#1132)

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

.changeset/modern-flies-joke.md

@@ -0,0 +1,6 @@
+---
+"myst-directives": minor
+"myst-spec-ext": minor
+---
+
+Add topic directive

docs/asides.md

@@ -6,19 +6,19 @@ description: Asides provide an easy way to represent content that is only indire
 
 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.
 
-```{aside}
+```{aside} Margin Content
 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)
 
 or any other sort of content!
 ```
 
-````markdown
-```{aside}
+```markdown
+:::{aside} An Optional Title
 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.
 
@@ -29,3 +29,21 @@ 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)).
 
 :::
+
+% Using bold here, until we fix #170
+
+**Topics**
+
+A topic is like a block quote with a title, or a self-contained section.
+Use the "topic" directive to indicate a self-contained idea that is separate from the flow of the document.
+Semantically, this is an `<aside>`.
+
+```markdown
+:::{topic} This is an optional topic title
+This is an topic, with standalone ideas.
+:::
+```
+
+:::{topic} This is an optional topic title
+This is an topic, with standalone ideas.
+:::

docs/directives.md

@@ -6,6 +6,9 @@ description: A full list of the directives included in MyST Markdown by default.
 :::{myst:directive} admonition
 :::
 
+:::{myst:directive} aside
+:::
+
 :::{myst:directive} bibliography
 :::
 
@@ -42,15 +45,9 @@ description: A full list of the directives included in MyST Markdown by default.
 :::{myst:directive} include
 :::
 
-:::{myst:directive} table
-:::
-
 :::{myst:directive} list-table
 :::
 
-:::{myst:directive} aside
-:::
-
 :::{myst:directive} math
 :::
 
@@ -65,3 +62,6 @@ description: A full list of the directives included in MyST Markdown by default.
 
 :::{myst:directive} output
 :::
+
+:::{myst:directive} table
+:::

packages/myst-directives/src/aside.ts

@@ -1,20 +1,45 @@
 import type { DirectiveSpec, DirectiveData, GenericNode } from 'myst-common';
 import type { Aside } from 'myst-spec-ext';
 import type { FlowContent, ListContent, PhrasingContent } from 'myst-spec';
+import { normalizeLabel } from 'myst-common';
 
 export const asideDirective: DirectiveSpec = {
   name: 'aside',
-  alias: ['margin', 'sidebar'],
+  alias: ['margin', 'sidebar', 'topic'],
+  arg: {
+    type: 'myst',
+    doc: 'An optional title',
+  },
+  options: {
+    label: {
+      type: String,
+      alias: ['name'],
+    },
+    class: {
+      type: String,
+    },
+  },
   body: {
     type: 'myst',
     required: true,
   },
   run(data: DirectiveData): GenericNode[] {
+    const { label, identifier } = normalizeLabel(data.options?.label as string | undefined) || {};
+    const children = [...(data.body as unknown as (FlowContent | ListContent | PhrasingContent)[])];
+    if (data.arg) {
+      children.unshift({
+        type: 'admonitionTitle',
+        children: data.arg,
+      } as any);
+    }
     const aside: Aside = {
       type: 'aside',
       kind:
         data.name == 'aside' || data.name == 'margin' ? undefined : (data.name as Aside['kind']),
-      children: data.body as (FlowContent | ListContent | PhrasingContent)[],
+      children,
+      class: data.options?.class as string | undefined,
+      label,
+      identifier,
     };
     return [aside];
   },

packages/myst-spec-ext/src/types.ts

@@ -246,6 +246,9 @@ export type Output = Node & {
 
 export type Aside = Node & {
   type: 'aside';
-  kind?: 'sidebar' | 'margin';
+  kind?: 'sidebar' | 'margin' | 'topic';
   children?: (FlowContent | ListContent | PhrasingContent)[];
+  identifier?: string;
+  label?: string;
+  class?: Image['class'];
 };