💬 Add epigraph, pull-quote and blockquote directive

.changeset/great-cobras-bake.md

@@ -0,0 +1,5 @@
+---
+"myst-cli": patch
+---
+
+Add pullquotes, blockquotes and epigraph directives

.changeset/orange-shrimps-relate.md

@@ -0,0 +1,5 @@
+---
+'myst-spec-ext': patch
+---
+
+Require `kind` for `Container`

.changeset/seven-roses-cough.md

@@ -0,0 +1,6 @@
+---
+"myst-directives": minor
+"myst-transforms": minor
+---
+
+Add support for epigraphs and pull-quotes using a new blockquote directive.

docs/directives.md

@@ -9,6 +9,9 @@ description: Code and code-blocks can be used to show programming languages.
 :::{myst:directive} bibliography
 :::
 
+:::{myst:directive} blockquote
+:::
+
 :::{myst:directive} code
 :::
 

docs/directives.mjs

@@ -25,8 +25,8 @@ function createOption(directive, optName, option) {
           optName === 'arg'
             ? 'Directive Argument'
             : optName === 'body'
-            ? 'Directive Body'
-            : optName,
+              ? 'Directive Body'
+              : optName,
         ),
       ]),
       ...(optType

docs/typography.md

@@ -111,11 +111,22 @@ See [](#abbreviations) for more information.
 
 ## Quotations
 
-Quotations are controlled with standard Markdown syntax, by inserting a caret (`>`) symbol in front of one or more lines of text. You can provide an attribution to a blockquote by adding `- author or source` to the final line.
+Quotations are controlled with standard Markdown syntax, by inserting a caret (`>`) symbol in front of one or more lines of text. You can provide an attribution to a blockquote by adding a final paragraph whose text starts with `--` or an em-dash (`—`), followed by the author or source. The blank `>` line is required!
 
 ```{myst}
 > We know what we are, but know not what we may be.
-> - Hamlet act 4, Scene 5
+>
+> -- Hamlet act 4, Scene 5
+```
+
+The quotes can also be created using a directive (either {myst:directive}`blockquote` or {myst:directive}`epigraph`), which allows you to add classes or labels to the quote. MyST also supports {myst:directive}`pull-quote` directive, which act as attention-grabbing visual elements.
+
+```{myst}
+:::{pull-quote}
+We know what we are, but know not what we may be.
+:::
+
+They say the owl was a baker’s daughter. Lord, we know what we are, but know not what we may be. God be at your table.
 ```
 
 (definition-lists)=

packages/myst-directives/package.json

@@ -32,6 +32,7 @@
     "url": "https://github.com/executablebooks/mystmd/issues"
   },
   "dependencies": {
+    "classnames": "^2.3.2",
     "js-yaml": "^4.1.0",
     "myst-common": "^1.1.29",
     "myst-spec-ext": "^1.1.29",

packages/myst-directives/src/blockquote.ts

@@ -0,0 +1,50 @@
+import type { DirectiveSpec, DirectiveData, GenericNode } from 'myst-common';
+import { normalizeLabel } from 'myst-common';
+import type { Container } from 'myst-spec-ext';
+import classNames from 'classnames';
+
+export const blockquoteDirective: DirectiveSpec = {
+  name: 'blockquote',
+  alias: ['epigraph', 'pull-quote'],
+  doc: 'Block quotes are used to indicate that the enclosed content forms an extended quotation. They may be followed by an inscription or attribution formed of a paragraph beginning with `--`, `---`, or an em-dash.',
+  options: {
+    label: {
+      type: String,
+      alias: ['name'],
+    },
+    class: {
+      type: String,
+      doc: `CSS classes to add to your blockquote. Special classes include:
+
+- \`pull-quote\`: used for a blockquote node which should attract attention
+- \`epigraph\`: used for a blockquote node that are usually found at the beginning of a document`,
+    },
+  },
+  body: {
+    type: 'myst',
+    doc: 'The body of the quote, which may contain a special attribution paragraph that is turned into a caption',
+  },
+  run(data: DirectiveData): GenericNode[] {
+    const children: GenericNode[] = [];
+    if (data.body) {
+      children.push(...(data.body as GenericNode[]));
+    }
+    const { label, identifier } = normalizeLabel(data.options?.label as string | undefined) || {};
+    const className = data.options?.class as string;
+    const container: Container = {
+      type: 'container',
+      kind: 'quote',
+      label,
+      identifier,
+      class: classNames({ [className]: className, [data.name]: data.name !== 'blockquote' }),
+      children: [
+        {
+          // @ts-expect-error: myst-spec needs updating to support blockquote
+          type: 'blockquote',
+          children: children as any[],
+        },
+      ],
+    };
+    return [container];
+  },
+};

packages/myst-directives/src/index.ts

@@ -15,6 +15,7 @@ import { mdastDirective } from './mdast.js';
 import { mermaidDirective } from './mermaid.js';
 import { mystdemoDirective } from './mystdemo.js';
 import { outputDirective } from './output.js';
+import { blockquoteDirective } from './blockquote.js';
 import { rawDirective } from './raw.js';
 
 export const defaultDirectives = [
@@ -24,6 +25,7 @@ export const defaultDirectives = [
   codeCellDirective,
   dropdownDirective,
   embedDirective,
+  blockquoteDirective,
   figureDirective,
   iframeDirective,
   imageDirective,
@@ -56,4 +58,5 @@ export { mdastDirective } from './mdast.js';
 export { mermaidDirective } from './mermaid.js';
 export { mystdemoDirective } from './mystdemo.js';
 export { outputDirective } from './output.js';
+export { blockquoteDirective } from './blockquote.js';
 export { rawDirective } from './raw.js';

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

@@ -225,7 +225,7 @@ export type Raw = {
 };
 
 export type Container = Omit<SpecContainer, 'kind'> & {
-  kind?: 'figure' | 'table' | 'quote' | 'code' | string;
+  kind: 'figure' | 'table' | 'quote' | 'code' | string;
   source?: Dependency;
   subcontainer?: boolean;
   noSubcontainers?: boolean;

packages/myst-transforms/src/blockquote.spec.ts

@@ -3,11 +3,175 @@ import { u } from 'unist-builder';
 import { blockquoteTransform } from './blockquote';
 
 describe('Test blockquoteTransform', () => {
-  test('simple code block returns self', async () => {
+  test('block-quote with attribution inside container preserves container', async (quote) => {
+    const mdast = u('root', [
+      u('container', { kind: 'quote', class: 'pull-quote' }, [
+        u('blockquote', [
+          u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+          u('paragraph', [u('text', '-- Hamlet'), u('strong', [u('text', 'act 4, Scene 5')])]),
+        ]),
+      ]),
+    ]);
+    blockquoteTransform(mdast);
+    expect(mdast).toEqual(
+      u('root', [
+        u('container', { kind: 'quote', class: 'pull-quote' }, [
+          u('blockquote', [
+            u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+          ]),
+          u('caption', [
+            u('paragraph', [u('text', 'Hamlet'), u('strong', [u('text', 'act 4, Scene 5')])]),
+          ]),
+        ]),
+      ]),
+    );
+  });
+  test('block-quote without attribution inside container drops container', async (quote) => {
+    const mdast = u('root', [
+      u('container', { kind: 'quote' }, [
+        u('blockquote', [
+          u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+          u('paragraph', [u('text', 'Hamlet'), u('strong', [u('text', 'act 4, Scene 5')])]),
+        ]),
+      ]),
+    ]);
+    blockquoteTransform(mdast);
+    expect(mdast).toEqual(
+      u('root', [
+        u('blockquote', [
+          u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+          u('paragraph', [u('text', 'Hamlet'), u('strong', [u('text', 'act 4, Scene 5')])]),
+        ]),
+      ]),
+    );
+  });
+  test('block-quote without attribution inside container with class preserves container', async (quote) => {
+    const mdast = u('root', [
+      u('container', { kind: 'quote', class: 'foo' }, [
+        u('blockquote', [
+          u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+          u('paragraph', [u('text', 'Hamlet'), u('strong', [u('text', 'act 4, Scene 5')])]),
+        ]),
+      ]),
+    ]);
+    blockquoteTransform(mdast);
+    expect(mdast).toEqual(
+      u('root', [
+        u('container', { kind: 'quote', class: 'foo' }, [
+          u('blockquote', [
+            u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+            u('paragraph', [u('text', 'Hamlet'), u('strong', [u('text', 'act 4, Scene 5')])]),
+          ]),
+        ]),
+      ]),
+    );
+  });
+  test('blockquote without attribution is unchanged', async () => {
     const mdast = u('root', [
       u('blockquote', [
         u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
-        u('list', { ordered: false }, [u('listItem', [u('text', 'Hamlet act 4, Scene 5')])]),
+        u('paragraph', [u('text', '(From Hamlet act 4, Scene 5)')]),
+      ]),
+    ]);
+    blockquoteTransform(mdast);
+    expect(mdast).toEqual(
+      u('root', [
+        u('blockquote', [
+          u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+          u('paragraph', [u('text', '(From Hamlet act 4, Scene 5)')]),
+        ]),
+      ]),
+    );
+  });
+  test('blockquote with malformed attribution is unchanged', async () => {
+    const mdast = u('root', [
+      u('blockquote', [
+        u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+        u('paragraph', [u('text', '?? -- Hamlet act 4, Scene 5')]),
+      ]),
+    ]);
+    blockquoteTransform(mdast);
+    expect(mdast).toEqual(
+      u('root', [
+        u('blockquote', [
+          u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+          u('paragraph', [u('text', '?? -- Hamlet act 4, Scene 5')]),
+        ]),
+      ]),
+    );
+  });
+  test.each(['---', '--', '—'])(
+    "blockquote with '%s'-format attribution becomes container",
+    async (quote) => {
+      const mdast = u('root', [
+        u('blockquote', [
+          u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+          u('paragraph', [
+            u('text', `${quote} Hamlet`),
+            u('strong', [u('text', 'act 4, Scene 5')]),
+          ]),
+        ]),
+      ]);
+      blockquoteTransform(mdast);
+      expect(mdast).toEqual(
+        u('root', [
+          u('container', { kind: 'quote' }, [
+            u('blockquote', [
+              u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+            ]),
+            u('caption', [
+              u('paragraph', [u('text', `Hamlet`), u('strong', [u('text', 'act 4, Scene 5')])]),
+            ]),
+          ]),
+        ]),
+      );
+    },
+  );
+  test.each(['---', '--', '—'])(
+    "blockquote with nested '%s'-format attribution becomes container of container",
+    async (quote) => {
+      const mdast = u('root', [
+        u('blockquote', [
+          u('blockquote', [
+            u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+            u('paragraph', [
+              u('text', `${quote} Hamlet`),
+              u('strong', [u('text', 'act 4, Scene 5')]),
+            ]),
+          ]),
+          u('paragraph', [
+            u('text', `${quote} Hamlet`),
+            u('strong', [u('text', 'act 4, Scene 5')]),
+          ]),
+        ]),
+      ]);
+      blockquoteTransform(mdast);
+      expect(mdast).toEqual(
+        u('root', [
+          u('container', { kind: 'quote' }, [
+            u('blockquote', [
+              u('container', { kind: 'quote' }, [
+                u('blockquote', [
+                  u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+                ]),
+                u('caption', [
+                  u('paragraph', [u('text', `Hamlet`), u('strong', [u('text', 'act 4, Scene 5')])]),
+                ]),
+              ]),
+            ]),
+            u('caption', [
+              u('paragraph', [u('text', `Hamlet`), u('strong', [u('text', 'act 4, Scene 5')])]),
+            ]),
+          ]),
+        ]),
+      );
+    },
+  );
+  test('blockquote with only-markup attribution loses text node', async () => {
+    const mdast = u('root', [
+      u('blockquote', [
+        u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+        u('paragraph', [u('text', '-- '), u('strong', [u('text', 'Hamlet act 4, Scene 5')])]),
       ]),
     ]);
     blockquoteTransform(mdast);
@@ -17,7 +181,24 @@ describe('Test blockquoteTransform', () => {
           u('blockquote', [
             u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
           ]),
-          u('caption', [u('paragraph', [u('text', 'Hamlet act 4, Scene 5')])]),
+          u('caption', [u('paragraph', [u('strong', [u('text', 'Hamlet act 4, Scene 5')])])]),
+        ]),
+      ]),
+    );
+  });
+  test('blockquote with empty attribution is unchanged', async () => {
+    const mdast = u('root', [
+      u('blockquote', [
+        u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+        u('paragraph', [u('text', '-- ')]),
+      ]),
+    ]);
+    blockquoteTransform(mdast);
+    expect(mdast).toEqual(
+      u('root', [
+        u('blockquote', [
+          u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+          u('paragraph', [u('text', '-- ')]),
         ]),
       ]),
     );