✅ Support for new GitHub admonitions

.changeset/tough-ghosts-raise.md

@@ -0,0 +1,5 @@
+---
+'myst-transforms': patch
+---
+
+Expand to allow for new github admonitions [!NOTE] in a blockquote

docs/admonitions.md

@@ -110,10 +110,23 @@ Here is an admonition!
 
 :::::::{tip} Compatibility with GitHub
 :class: dropdown
-GitHub markdown transforms blockquotes that start with a bold `Note` or `Warning` into a simple admonition (see [GitHub](https://github.com/community/community/discussions/16925)). MyST also transforms these blockquotes into the appropriate admonitions with a `simple` class.
+GitHub markdown transforms blockquotes that start with a bold `Note` or text with `[!NOTE]` into a simple admonition (see [GitHub](https://github.com/community/community/discussions/16925)). This syntax only works for `note`, `important` or `warning`. MyST transforms these blockquotes into the appropriate admonitions with a `simple` class.
 
 ```{myst}
-> **Note** This is a note!
+> [!NOTE]
+> Highlights information that users should take into account, even when skimming.
+
+> [!IMPORTANT]
+> Crucial information necessary for users to succeed.
+
+> [!WARNING]
+> Critical content demanding immediate user attention due to potential risks.
+
+> **Note**
+> This is a note
+
+> **Warning**
+> This is a warning
 ```
 
 :::::::

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

@@ -4,7 +4,7 @@ import type { Root } from 'mdast';
 import { admonitionBlockquoteTransform, admonitionHeadersTransform } from './admonitions';
 
 describe('Test admonitionBlockquoteTransform', () => {
-  test('simple code block returns self', async () => {
+  test('blockquote bold admonition', async () => {
     const mdast = u('root', [
       u('blockquote', [
         u('paragraph', [
@@ -24,4 +24,21 @@ describe('Test admonitionBlockquoteTransform', () => {
       ]),
     );
   });
+  test('blockquote [!NOTE] admonition', async () => {
+    const mdast = u('root', [
+      u('blockquote', [
+        u('paragraph', [u('text', '[!NOTE] We know what we are, but know not what we may be.')]),
+      ]),
+    ]);
+    admonitionBlockquoteTransform(mdast as Root);
+    admonitionHeadersTransform(mdast as Root);
+    expect(mdast).toEqual(
+      u('root', [
+        u('admonition', { kind: 'note', class: 'simple' }, [
+          u('admonitionTitle', [u('text', 'Note')]),
+          u('paragraph', [u('text', 'We know what we are, but know not what we may be.')]),
+        ]),
+      ]),
+    );
+  });
 });

packages/myst-transforms/src/admonitions.ts

@@ -10,7 +10,7 @@ type Options = {
   replaceAdmonitionTitles?: boolean;
 };
 
-const githubAdmonitionKinds = ['note', 'warning'];
+const githubAdmonitionKinds = ['note', 'important', 'warning'];
 
 export function admonitionKindToTitle(kind: AdmonitionKind | string) {
   const transform: Record<string, string> = {
@@ -70,34 +70,65 @@ export function admonitionHeadersTransform(tree: Root, opts?: Options) {
   });
 }
 
+function transformGitHubBoldTitle(node: GenericNode): boolean {
+  if (
+    !node.children ||
+    node.children?.[0]?.type !== 'paragraph' ||
+    node.children[0].children?.[0]?.type !== 'strong'
+  ) {
+    return false;
+  }
+  const strong = node.children[0].children[0];
+  if (strong.children?.[0].type !== 'text') return false;
+  const kind = strong.children[0].value?.trim().toLowerCase() ?? '';
+  if (!githubAdmonitionKinds.includes(kind)) return false;
+  node.type = 'admonition';
+  node.kind = kind;
+  node.class = node.class ? node.class + ' simple' : 'simple';
+  node.children[0].children.splice(0, 1); // Get rid of the strong node
+  node.children = [
+    {
+      type: 'admonitionTitle',
+      children: [{ type: 'text', value: admonitionKindToTitle(node.kind) }],
+    },
+    ...node.children,
+  ];
+  return true;
+}
+
+function transformGitHubBracketedAdmonition(node: GenericNode): boolean {
+  if (!node.children || node.children?.[0]?.type !== 'paragraph') return false;
+  const firstNode = node.children[0]?.children?.[0];
+  if (firstNode?.type !== 'text') return false;
+  const match = firstNode.value?.trim().match(/^\[!([A-Za-z]+)\]/);
+  if (!match) return false;
+  const [, kind] = match;
+  if (!githubAdmonitionKinds.includes(kind.toLowerCase())) return false;
+  node.type = 'admonition';
+  node.kind = kind.toLowerCase();
+  node.class = node.class ? node.class + ' simple' : 'simple';
+  firstNode.value = firstNode.value?.replace(/^\[!([A-Za-z]+)\](?:[\s]*)/, '');
+  node.children = [
+    {
+      type: 'admonitionTitle',
+      children: [{ type: 'text', value: admonitionKindToTitle(node.kind) }],
+    },
+    ...node.children,
+  ];
+  return true;
+}
+
 /**
  * Visit all blockquote notes and add headers if necessary, support GitHub style admonitions
  */
 export function admonitionBlockquoteTransform(tree: Root) {
   const blockquote = selectAll('blockquote', tree) as Blockquote[];
   blockquote.forEach((node: GenericNode) => {
-    if (
-      !node.children ||
-      node.children?.[0]?.type !== 'paragraph' ||
-      node.children[0].children?.[0]?.type !== 'strong'
-    ) {
-      return;
-    }
-    const strong = node.children[0].children[0];
-    if (strong.children?.[0].type !== 'text') return;
-    const kind = strong.children[0].value?.trim().toLowerCase() ?? '';
-    if (!githubAdmonitionKinds.includes(kind)) return;
-    node.type = 'admonition';
-    node.kind = kind;
-    node.class = node.class ? node.class + ' simple' : 'simple';
-    node.children[0].children.splice(0, 1); // Get rid of the strong node
-    node.children = [
-      {
-        type: 'admonitionTitle',
-        children: [{ type: 'text', value: admonitionKindToTitle(node.kind) }],
-      },
-      ...node.children,
-    ];
+    // Loop through the various flavours of blockquote admonitions and return early if already transformed
+    [transformGitHubBracketedAdmonition, transformGitHubBoldTitle].reduce(
+      (complete, fn) => complete || fn(node),
+      false,
+    );
   });
 }