Merge pull request #122 from CooperRedhat/markdown-admonitions

Add showdown extension for admonitions through markdown syntax

packages/dev/src/quickstarts-data/yaml/template.yaml

@@ -7,7 +7,7 @@ spec:
   displayName: Getting started with quick starts
   durationMinutes: 10
   # Optional type section, will display as a tile on the card
-  type: 
+  type:
     text: Type
     # 'blue' | 'cyan' | 'green' | 'orange' | 'purple' | 'red' | 'grey'
     color: grey
@@ -71,6 +71,20 @@ spec:
 
         - Clicking the _Next_ button will display the **Check your work** module.
 
+        ### Admonition blocks
+
+        The syntax for rendering "Admonition Blocks" to Patternfly React Alerts:
+        - Bracketed alert text contents
+        - The admonition keyword, followed by the alert variant you want
+        - Variants are: note, tip, important, caution, and warning
+
+        **Examples**
+        [This is the note contents]{{admonition note}}
+        [This is the tip contents]{{admonition tip}}
+        [This is the important contents]{{admonition important}}
+        [This is the caution contents]{{admonition caution}}
+        [This is the warning contents]{{admonition warning}}
+
       # optional - the task's Check your work module
       review:
         instructions: |-

packages/module/src/ConsoleShared/src/components/markdown-extensions/admonition-extension.tsx

@@ -0,0 +1,66 @@
+import * as React from 'react';
+import { removeTemplateWhitespace } from './utils';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { Alert } from '@patternfly/react-core';
+import LightbulbIcon from '@patternfly/react-icons/dist/js/icons/lightbulb-icon';
+import FireIcon from '@patternfly/react-icons/dist/js/icons/fire-icon';
+import './showdown-extension.scss';
+
+enum AdmonitionType {
+  TIP = 'TIP',
+  NOTE = 'NOTE',
+  IMPORTANT = 'IMPORTANT',
+  WARNING = 'WARNING',
+  CAUTION = 'CAUTION',
+}
+
+const admonitionToAlertVariantMap = {
+  [AdmonitionType.NOTE]: { variant: 'info' },
+  [AdmonitionType.TIP]: { variant: 'default', customIcon: <LightbulbIcon /> },
+  [AdmonitionType.IMPORTANT]: { variant: 'danger' },
+  [AdmonitionType.CAUTION]: { variant: 'warning', customIcon: <FireIcon /> },
+  [AdmonitionType.WARNING]: { variant: 'warning' },
+};
+
+const useAdmonitionShowdownExtension = () => {
+  // const { getResource } = React.useContext<QuickStartContextValues>(QuickStartContext);
+  return React.useMemo(
+    () => ({
+      type: 'lang',
+      regex: /\[([\d\w\s-()$!]+)]{{(admonition) ([\w-]+)}}/g,
+      replace: (
+        text: string,
+        content: string,
+        admonitionLabel: string,
+        admonitionType: string,
+        groupId: string,
+      ): string => {
+        if (!content || !admonitionLabel || !admonitionType || !groupId) {
+          return text;
+        }
+        admonitionType = admonitionType.toUpperCase();
+
+        const { variant, customIcon } = admonitionToAlertVariantMap[admonitionType];
+        const style =
+          admonitionType === AdmonitionType.CAUTION ? { backgroundColor: '#ec7a0915' } : {};
+
+        const pfAlert = (
+          <Alert
+            variant={variant}
+            customIcon={customIcon && customIcon}
+            isInline
+            title={admonitionType}
+            className="pfext-markdown-admonition"
+            style={style}
+          >
+            {content}
+          </Alert>
+        );
+        return removeTemplateWhitespace(renderToStaticMarkup(pfAlert));
+      },
+    }),
+    [],
+  );
+};
+
+export default useAdmonitionShowdownExtension;

packages/module/src/ConsoleShared/src/components/markdown-extensions/index.ts

@@ -1,3 +1,4 @@
 export { default as MarkdownCopyClipboard } from './MarkdownCopyClipboard';
 export { default as useInlineCopyClipboardShowdownExtension } from './inline-clipboard-extension';
 export { default as useMultilineCopyClipboardShowdownExtension } from './multiline-clipboard-extension';
+export { default as useAdmonitionShowdownExtension } from './admonition-extension';

packages/module/src/ConsoleShared/src/components/markdown-extensions/showdown-extension.scss

@@ -31,4 +31,22 @@
       }
     }
   }
+
+  .pfext-markdown-admonition {
+    &.pf-c-alert {
+      // add margins to match design
+      margin: var(--pf-global--spacer--md) 0;
+      .pf-c-alert__title {
+        // remove margins from markdown css
+        margin-top: 0;
+        margin-bottom: 0;
+        // lift PF style specificity to override markdown css
+        font-weight: var(--pf-c-alert__title--FontWeight);
+        font-family: inherit;
+        line-height: inherit;
+        color: var(--pf-c-alert__title--Color);
+        word-break: break-word;
+      }
+    }
+  }
 }

packages/module/src/QuickStartMarkdownView.tsx

@@ -5,6 +5,7 @@ import {
   MarkdownHighlightExtension,
   useInlineCopyClipboardShowdownExtension,
   useMultilineCopyClipboardShowdownExtension,
+  useAdmonitionShowdownExtension,
 } from '@console/shared';
 import { HIGHLIGHT_REGEXP } from '@console/shared/src/components/markdown-highlight-extension/highlight-consts';
 import { QuickStartContext, QuickStartContextValues } from './utils/quick-start-context';
@@ -25,6 +26,7 @@ const QuickStartMarkdownView: React.FC<QuickStartMarkdownViewProps> = ({
   const { markdown } = React.useContext<QuickStartContextValues>(QuickStartContext);
   const inlineCopyClipboardShowdownExtension = useInlineCopyClipboardShowdownExtension();
   const multilineCopyClipboardShowdownExtension = useMultilineCopyClipboardShowdownExtension();
+  const admonitionShowdownExtension = useAdmonitionShowdownExtension();
   return (
     <SyncMarkdownView
       inline
@@ -51,6 +53,7 @@ const QuickStartMarkdownView: React.FC<QuickStartMarkdownViewProps> = ({
         },
         inlineCopyClipboardShowdownExtension,
         multilineCopyClipboardShowdownExtension,
+        admonitionShowdownExtension,
         ...(markdown ? markdown.extensions : []),
       ]}
       renderExtension={(docContext, rootSelector) => (