🧮 Add inline options to roles and directives (#1822)

Author: rowanc1

.changeset/healthy-kangaroos-applaud.md

@@ -0,0 +1,5 @@
+---
+"markdown-it-myst": patch
+---
+
+Add inline options

.changeset/pink-birds-join.md

@@ -0,0 +1,6 @@
+---
+"myst-directives": patch
+"myst-transforms": patch
+---
+
+Move QMD admonition recognition to a transform

.changeset/small-paws-suffer.md

@@ -0,0 +1,5 @@
+---
+"myst-directives": patch
+---
+
+div node does not require a body

.changeset/tough-terms-push.md

@@ -0,0 +1,5 @@
+---
+"myst-roles": patch
+---
+
+Introduce a span role

docs/inline-options.md

@@ -0,0 +1,54 @@
+---
+title: Inline Options
+subtitle: Concise specification of CSS classes, IDs, and attributes
+description: MyST Markdown has support for inline attributes for both roles and directives, allowing concise specification of CSS classes, IDs, and attributes. This complements other methods for defining options, making markup more expressive and flexible.
+# thumbnail: thumbnails/inline-options.png
+---
+
+:::{warning} Inline Options are in Beta
+The support for inline attributes is in beta and may have some bugs or limitations.
+Please give feedback on [GitHub](https://github.com/orgs/jupyter-book/discussions).
+:::
+
+MyST Markdown has support for inline attributes for both roles and directives, allowing concise specification of CSS classes, IDs, and attributes. This complements other methods for defining options, making markup more expressive and flexible.
+
+```markdown
+:::{tip .dropdown open="true"} Title
+Tip Content
+:::
+```
+
+This can also be used for roles:
+
+`` {span .text-red-500}`Red text` ``
+
+{span .text-red-500}`Red text`
+
+## Syntax Overview
+
+The inline attribute syntax follows this pattern:
+
+````text
+{role #id .class key="value" key=value}`content`
+
+```{directive #id .class key="value" key=value}
+content
+```
+````
+
+Name (e.g. `tip` or `cite:p`)
+: The directive or role name must come first. There must only be a single "bare" token.
+
+ID (`#id`)
+: Defines the label/identifier of the node
+
+Class (`.class`)
+: Adds CSS class(es).
+
+Quoted Attributes (`key="value"`)
+: Supports attributes containing spaces or special characters.
+
+Unquoted Attributes (`key=value` or `key=123`)
+: Allows simpler attribute values when there are no spaces.
+
+For directives, these can be mixed with other ways to define options on directives, classes are combined in a single space-separated string; other repeated directive options will raise a duplicate option warning.

docs/myst.yml

@@ -101,6 +101,7 @@ project:
         - file: glossaries-and-terms.md
         - file: writing-in-latex.md
         - file: table-of-contents.md
+        - file: inline-options.md
     - title: Executable Content
       children:
         - file: notebooks-with-markdown.md

docs/syntax-overview.md

@@ -63,7 +63,7 @@ My directive content.
 
 2\) **directive options** - a collection of flags or key/value pairs that come just underneath `{directivename}`.
 
-There are two ways to write directive options, as `:key: value` or as a YAML block.
+There are three ways to write directive options: as `:key: value`, as a YAML block, or directly inline.
 
 ``````{tab-set}
 `````{tab-item} Key value pairs
@@ -89,6 +89,14 @@ key1: metadata1
 key2: metadata2
 ---
 
+My directive content.
+```
+````
+`````
+`````{tab-item} Inline Options
+Options can be included inline. See [](./inline-options.md) for more information.
+````markdown
+```{directivename .class-name #label key="value"}
 My directive content.
 ```
 ````
@@ -117,6 +125,12 @@ Roles are defined inline, with an identifier and input. There are a number of ro
 Here is an {abc}`unknown role`.
 ```
 
+Options for roles can be included inline. See [](./inline-options.md) for more information.
+
+```markdown
+Here is my {span #label .class-name key="value"}`custom span`.
+```
+
 (nesting-content)=
 
 ## Nesting content blocks in Markdown

packages/markdown-it-myst/src/directives.ts

@@ -5,6 +5,7 @@ import type MarkdownIt from 'markdown-it/lib';
 import type StateCore from 'markdown-it/lib/rules_core/state_core.js';
 import { nestedPartToTokens } from './nestedParse.js';
 import { stateError, stateWarn } from './utils.js';
+import { inlineOptionsToTokens } from './inlineAttributes.js';
 
 const COLON_OPTION_REGEX = /^:(?<option>[^:\s]+?):(\s*(?<value>.*)){0,1}\s*$/;
 
@@ -26,7 +27,7 @@ function computeBlockTightness(
 function replaceFences(state: StateCore): boolean {
   for (const token of state.tokens) {
     if (token.type === 'fence' || token.type === 'colon_fence') {
-      const match = token.info.match(/^\s*\{\s*([^}\s]+)\s*\}\s*(.*)$/);
+      const match = token.info.match(/^\s*\{\s*([^}]+)\s*\}\s*(.*)$/);
       if (match) {
         token.type = 'directive';
         token.info = match[1].trim();
@@ -45,38 +46,49 @@ function runDirectives(state: StateCore): boolean {
       try {
         const { info, map } = token;
         const arg = token.meta.arg?.trim() || undefined;
+        const {
+          name = 'div',
+          tokens: inlineOptTokens,
+          options: inlineOptions,
+        } = inlineOptionsToTokens(info, map?.[0] ?? 0, state);
         const content = parseDirectiveContent(
           token.content.trim() ? token.content.split(/\r?\n/) : [],
-          info,
+          name,
           state,
         );
-        const { body, options } = content;
+        const { body, options, optionsLocation } = content;
         let { bodyOffset } = content;
         while (body.length && !body[0].trim()) {
           body.shift();
           bodyOffset++;
         }
         const bodyString = body.join('\n').trimEnd();
         const directiveOpen = new state.Token('parsed_directive_open', '', 1);
-        directiveOpen.info = info;
+        directiveOpen.info = name;
         directiveOpen.hidden = true;
         directiveOpen.content = bodyString;
         directiveOpen.map = map;
         directiveOpen.meta = {
           arg,
-          options: getDirectiveOptions(options),
+          options: getDirectiveOptions([...inlineOptions, ...(options ?? [])]),
           // Tightness is computed for all directives (are they separated by a newline before/after)
           tight: computeBlockTightness(state.src, token.map),
         };
         const startLineNumber = map ? map[0] : 0;
         const argTokens = directiveArgToTokens(arg, startLineNumber, state);
-        const optsTokens = directiveOptionsToTokens(options || [], startLineNumber + 1, state);
+        const optsTokens = directiveOptionsToTokens(
+          options || [],
+          startLineNumber + 1,
+          state,
+          optionsLocation,
+        );
         const bodyTokens = directiveBodyToTokens(bodyString, startLineNumber + bodyOffset, state);
         const directiveClose = new state.Token('parsed_directive_close', '', -1);
         directiveClose.info = info;
         directiveClose.hidden = true;
         const newTokens = [
           directiveOpen,
+          ...inlineOptTokens,
           ...argTokens,
           ...optsTokens,
           ...bodyTokens,
@@ -110,6 +122,7 @@ function parseDirectiveContent(
   body: string[];
   bodyOffset: number;
   options?: [string, string | true][];
+  optionsLocation?: 'yaml' | 'colon';
 } {
   let bodyOffset = 1;
   let yamlBlock: string[] | null = null;
@@ -136,7 +149,12 @@ function parseDirectiveContent(
     try {
       const options = yaml.load(yamlBlock.join('\n')) as Record<string, any>;
       if (options && typeof options === 'object') {
-        return { body: newContent, options: Object.entries(options), bodyOffset };
+        return {
+          body: newContent,
+          options: Object.entries(options),
+          bodyOffset,
+          optionsLocation: 'yaml',
+        };
       }
     } catch (err) {
       stateWarn(
@@ -162,7 +180,7 @@ function parseDirectiveContent(
         bodyOffset++;
       }
     }
-    return { body: newContent, options, bodyOffset };
+    return { body: newContent, options, bodyOffset, optionsLocation: 'colon' };
   }
   return { body: content, bodyOffset: 1 };
 }
@@ -172,9 +190,13 @@ function directiveArgToTokens(arg: string, lineNumber: number, state: StateCore)
 }
 
 function getDirectiveOptions(options?: [string, string | true][]) {
-  if (!options) return undefined;
+  if (!options || options.length === 0) return undefined;
   const simplified: Record<string, string | true> = {};
   options.forEach(([key, val]) => {
+    if (key === 'class' && simplified.class) {
+      simplified.class += ` ${val}`;
+      return;
+    }
     if (simplified[key] !== undefined) {
       return;
     }
@@ -187,28 +209,29 @@ function directiveOptionsToTokens(
   options: [string, string | true][],
   lineNumber: number,
   state: StateCore,
+  optionsLocation?: 'yaml' | 'colon',
 ) {
   const tokens = options.map(([key, value], index) => {
     // lineNumber mapping assumes each option is only one line;
     // not necessarily true for yaml options.
     const optTokens =
       typeof value === 'string'
         ? nestedPartToTokens(
-            'directive_option',
+            'myst_option',
             value,
             lineNumber + index,
             state,
             'run_directives',
             true,
           )
         : [
-            new state.Token('directive_option_open', '', 1),
-            new state.Token('directive_option_close', '', -1),
+            new state.Token('myst_option_open', '', 1),
+            new state.Token('myst_option_close', '', -1),
           ];
     if (optTokens.length) {
       optTokens[0].info = key;
       optTokens[0].content = typeof value === 'string' ? value : '';
-      optTokens[0].meta = { value };
+      optTokens[0].meta = { location: optionsLocation, value };
     }
     return optTokens;
   });

packages/markdown-it-myst/src/inlineAttributes.spec.ts

@@ -0,0 +1,99 @@
+// parseRoleHeader.spec.ts
+import { describe, expect, test } from 'vitest';
+import { inlineOptionsToTokens, tokenizeInlineAttributes } from './inlineAttributes';
+
+describe('parseRoleHeader', () => {
+  // Good (valid) test cases
+  test.each([
+    ['simple', [{ kind: 'bare', value: 'simple' }]],
+    [
+      'someRole .cls1 .cls2',
+      [
+        { kind: 'bare', value: 'someRole' },
+        { kind: 'class', value: 'cls1' },
+        { kind: 'class', value: 'cls2' },
+      ],
+    ],
+    [
+      'myRole #foo',
+      [
+        { kind: 'bare', value: 'myRole' },
+        { kind: 'id', value: 'foo' },
+      ],
+    ],
+    [
+      'myRole .red #xyz attr="value"',
+      [
+        { kind: 'bare', value: 'myRole' },
+        { kind: 'class', value: 'red' },
+        { kind: 'id', value: 'xyz' },
+        { kind: 'attr', key: 'attr', value: 'value' },
+      ],
+    ],
+    [
+      'roleName data="some \\"escaped\\" text"',
+      [
+        { kind: 'bare', value: 'roleName' },
+        { kind: 'attr', key: 'data', value: 'some "escaped" text' },
+      ],
+    ],
+    ['.className', [{ kind: 'class', value: 'className' }]],
+    [
+      'myRole open=true',
+      [
+        { kind: 'bare', value: 'myRole' },
+        { kind: 'attr', key: 'open', value: 'true' },
+      ],
+    ],
+    [
+      'myRole open=""',
+      [
+        { kind: 'bare', value: 'myRole' },
+        { kind: 'attr', key: 'open', value: '' },
+      ],
+    ],
+    [
+      'myRole #foo.',
+      [
+        { kind: 'bare', value: 'myRole' },
+        { kind: 'unknown', value: '#foo.' },
+      ],
+    ],
+    [
+      'myRole foo="{testing .blah}`content`"',
+      [
+        { kind: 'bare', value: 'myRole' },
+        { kind: 'attr', key: 'foo', value: '{testing .blah}`content`' },
+      ],
+    ],
+    ['cite:p', [{ kind: 'bare', value: 'cite:p' }]],
+    ['CITE:P', [{ kind: 'bare', value: 'CITE:P' }]],
+    ['1', [{ kind: 'bare', value: '1' }]],
+    ['    abc   ', [{ kind: 'bare', value: 'abc' }]],
+    [
+      'half-quote blah="asdf',
+      [
+        { kind: 'bare', value: 'half-quote' },
+        { kind: 'unknown', value: 'blah="asdf' },
+      ],
+    ],
+  ])('parses valid header: %s', (header, expected) => {
+    const result = tokenizeInlineAttributes(header);
+    expect(result).toEqual(expected);
+  });
+
+  // Error test cases
+  test.each([
+    [
+      'Extra bare token after name',
+      'myRole anotherWord',
+      'No additional bare tokens allowed after the first token',
+    ],
+    ['Multiple IDs', 'myRole #first #second', 'Cannot have more than one ID defined'],
+    ['ID starts with a digit', 'myRole #1bad', 'ID cannot start with a number: "1bad"'],
+    ['Unknown token', 'myRole #bad.', 'Unknown token "#bad."'],
+    ['Unknown token', 'myRole .class.no.space', 'Classes must be separated by spaces'],
+  ])('throws error: %s', (_, header, expectedMessage) => {
+    expect(() => inlineOptionsToTokens(header, 0, null as any)).toThrow(expectedMessage);
+  });
+});