From b688080feda488ff823f63b40d09fa7b38de94fa Mon Sep 17 00:00:00 2001
From: Angus Hollands <goosey15@gmail.com>
Date: Wed, 20 Mar 2024 10:11:24 +0000
Subject: [PATCH] feat: add `aside` directive

---
 .changeset/brave-comics-confess.md     |  5 +++++
 docs/directives.md                     |  2 +-
 packages/myst-directives/src/aside.ts  | 21 +++++++++++++++++++++
 packages/myst-directives/src/index.ts  |  6 +++---
 packages/myst-directives/src/margin.ts | 17 -----------------
 packages/myst-spec-ext/src/types.ts    |  7 +++++++
 6 files changed, 37 insertions(+), 21 deletions(-)
 create mode 100644 .changeset/brave-comics-confess.md
 create mode 100644 packages/myst-directives/src/aside.ts
 delete mode 100644 packages/myst-directives/src/margin.ts

diff --git a/.changeset/brave-comics-confess.md b/.changeset/brave-comics-confess.md
new file mode 100644
index 000000000..ede42feda
--- /dev/null
+++ b/.changeset/brave-comics-confess.md
@@ -0,0 +1,5 @@
+---
+"myst-directives": minor
+---
+
+Add `aside` directive
diff --git a/docs/directives.md b/docs/directives.md
index 511499e8b..02c33ec64 100644
--- a/docs/directives.md
+++ b/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
diff --git a/packages/myst-directives/src/aside.ts b/packages/myst-directives/src/aside.ts
new file mode 100644
index 000000000..aaa9decc9
--- /dev/null
+++ b/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];
+  },
+};
diff --git a/packages/myst-directives/src/index.ts b/packages/myst-directives/src/index.ts
index 0db6bcb18..39f99b95f 100644
--- a/packages/myst-directives/src/index.ts
+++ b/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';
diff --git a/packages/myst-directives/src/margin.ts b/packages/myst-directives/src/margin.ts
deleted file mode 100644
index d4f7f9ecb..000000000
--- a/packages/myst-directives/src/margin.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-import type { DirectiveSpec, DirectiveData, GenericNode } from 'myst-common';
-
-export const marginDirective: DirectiveSpec = {
-  name: 'margin',
-  body: {
-    type: 'myst',
-    required: true,
-  },
-  run(data: DirectiveData): GenericNode[] {
-    return [
-      {
-        type: 'margin',
-        children: data.body as GenericNode[],
-      },
-    ];
-  },
-};
diff --git a/packages/myst-spec-ext/src/types.ts b/packages/myst-spec-ext/src/types.ts
index 8318550af..90a46ef00 100644
--- a/packages/myst-spec-ext/src/types.ts
+++ b/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)[];
+}