Fix up docs

.changeset/great-cobras-bake.md

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

.changeset/orange-shrimps-relate.md

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

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,24 +111,24 @@ 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 a final paragraph whose text starts with `--` or an emdash (`—`), followed by the author or source`. The blank `>` line is required!
+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
 ```
 
-MyST also supports pull-quotes via the `pull-quote` directive, which act as attention-grabbing visual elements.
+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
+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.
+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)=
 
 ## Definition Lists

packages/myst-directives/src/blockquote.ts

@@ -3,7 +3,7 @@ import { normalizeLabel } from 'myst-common';
 import type { Container } from 'myst-spec-ext';
 import classNames from 'classnames';
 
-export const blockQuoteDirective: DirectiveSpec = {
+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.',
@@ -14,15 +14,15 @@ export const blockQuoteDirective: DirectiveSpec = {
     },
     class: {
       type: String,
-      doc: `CSS classes to add to your block-quote. Special classes include:
+      doc: `CSS classes to add to your blockquote. Special classes include:
 
-- \`pull-quote\`: used for block-quotes which should attract attention
-- \`epigraph\`: used for block-quotes that are usually found at the beginning of a document`,
+- \`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.',
+    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[] = [];
@@ -36,7 +36,7 @@ export const blockQuoteDirective: DirectiveSpec = {
       kind: 'quote',
       label,
       identifier,
-      class: classNames({ [className]: className, [data.name]: data.name !== 'block-quote' }),
+      class: classNames({ [className]: className, [data.name]: data.name !== 'blockquote' }),
       children: [
         {
           // @ts-expect-error: myst-spec needs updating to support blockquote

packages/myst-directives/src/index.ts

@@ -15,7 +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 { blockquoteDirective } from './blockquote.js';
 import { rawDirective } from './raw.js';
 
 export const defaultDirectives = [
@@ -25,7 +25,7 @@ export const defaultDirectives = [
   codeCellDirective,
   dropdownDirective,
   embedDirective,
-  blockQuoteDirective,
+  blockquoteDirective,
   figureDirective,
   iframeDirective,
   imageDirective,
@@ -58,5 +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 { blockquoteDirective } from './blockquote.js';
 export { rawDirective } from './raw.js';