feat: add aside directive

.changeset/brave-comics-confess.md

@@ -0,0 +1,5 @@
+---
+"myst-directives": minor
+---
+
+Add `aside` directive

docs/directives.md

@@ -45,7 +45,7 @@ description: Code and code-blocks can be used to show programming languages.
 :::{myst:directive} list-table
 :::
 
-:::{myst:directive} margin
+:::{myst:directive} aside
 :::
 
 :::{myst:directive} math

packages/myst-directives/src/aside.ts

@@ -0,0 +1,21 @@
+import type { DirectiveSpec, DirectiveData, GenericNode } from 'myst-common';
+import type { Aside } from 'myst-spec-ext';
+import type { FlowContent, ListContent, PhrasingContent } from 'myst-spec';
+
+export const asideDirective: DirectiveSpec = {
+  name: 'aside',
+  alias: ['margin', 'sidebar'],
+  body: {
+    type: 'myst',
+    required: true,
+  },
+  run(data: DirectiveData): GenericNode[] {
+    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)[],
+    };
+    return [aside];
+  },
+};

packages/myst-directives/src/index.ts

@@ -8,7 +8,7 @@ import { iframeDirective } from './iframe.js';
 import { imageDirective } from './image.js';
 import { includeDirective } from './include.js';
 import { tableDirective, listTableDirective } from './table.js';
-import { marginDirective } from './margin.js';
+import { asideDirective } from './aside.js';
 import { glossaryDirective } from './glossary.js';
 import { mathDirective } from './math.js';
 import { mdastDirective } from './mdast.js';
@@ -32,7 +32,7 @@ export const defaultDirectives = [
   includeDirective,
   tableDirective,
   listTableDirective,
-  marginDirective,
+  asideDirective,
   glossaryDirective,
   mathDirective,
   mdastDirective,
@@ -52,7 +52,7 @@ export { iframeDirective } from './iframe.js';
 export { imageDirective } from './image.js';
 export { includeDirective } from './include.js';
 export { listTableDirective, tableDirective } from './table.js';
-export { marginDirective } from './margin.js';
+export { asideDirective } from './aside.js';
 export { mathDirective } from './math.js';
 export { mdastDirective } from './mdast.js';
 export { mermaidDirective } from './mermaid.js';

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

@@ -242,3 +242,10 @@ export type Output = Node & {
   visibility?: Visibility;
   children?: (FlowContent | ListContent | PhrasingContent)[];
 };
+
+
+export type Aside = Node & {
+  type: 'aside';
+  kind?: 'sidebar'
+  children?: (FlowContent | ListContent | PhrasingContent)[];
+}