feat: mermaid diagrams (#994)

[![PR App][icn]][demo] | Fix RM-10840 :-------------------:|:----------: ## 🧰 Changes - Support `Mermaid` as a code block language - If it's a single diagram, render without a code block - If there's multiple tabs, render within a code block <img width="800" alt="image" src="https://github.com/user-attachments/assets/a118b556-e949-4ab3-beab-174fd02f9f26"> <img width="800" alt="image" src="https://github.com/user-attachments/assets/b62a3db2-84e3-4194-a547-49e2d1f6ad02"> ## 🧬 QA & Testing - [Broken on production][prod]. - [Working in this PR app][demo]. [demo]: https://markdown-pr-PR_NUMBER.herokuapp.com [prod]: https://SUBDOMAIN.readme.io [icn]: https://user-images.githubusercontent.com/886627/160426047-1bee9488-305a-4145-bb2b-09d8b757d38a.svg --------- Co-authored-by: Kelly Joseph Price <[email protected]>
readmeio · Oct 22, 2024 · af6e306 · af6e306
1 parent 8c96e92
commit af6e306
Show file tree

Hide file tree

Showing 10 changed files with 1,045 additions and 37 deletions.
diff --git a/...l-regression-tests-rdmd-syntax-renders-code-blocks-without-surprises-1-snap.png b/...l-regression-tests-rdmd-syntax-renders-code-blocks-without-surprises-1-snap.png
diff --git a/components/Code/index.tsx b/components/Code/index.tsx
@@ -57,6 +57,10 @@ const Code = (props: CodeProps) => {
   const code = value ?? (Array.isArray(children) ? children[0] : children) ?? '';
   const highlightedCode = syntaxHighlighter && code ? syntaxHighlighter(code, language, codeOpts, { mdx: true }) : code;
 
+  if (language === 'mermaid') {
+    return code;
+  }
+
   return (
     <>
       {copyButtons && <CopyCode className="fa" codeRef={codeRef} />}

diff --git a/components/Code/style.scss b/components/Code/style.scss
@@ -84,6 +84,12 @@
     word-wrap: normal;
   }
 
+  pre.mermaid {
+    &_single {
+      background: var(--color-bg-page, white);
+    }
+  }
+
   kbd {
     background-color: $background;
     background-color: var(--d-code-background, $background);

diff --git a/components/CodeTabs/index.tsx b/components/CodeTabs/index.tsx
@@ -1,9 +1,17 @@
 import { uppercase } from '@readme/syntax-highlighter';
-import React from 'react';
+import React, { useEffect } from 'react';
+import mermaid from 'mermaid';
 
 const CodeTabs = props => {
   const { children, theme } = props;
 
+  // set Mermaid theme
+  useEffect(() => {
+    mermaid.initialize({
+      theme: theme === 'dark' ? 'dark' : 'default',
+    });
+  }, [theme])
+
   function handleClick({ target }, index: number) {
     const $wrap = target.parentElement.parentElement;
     const $open = [].slice.call($wrap.querySelectorAll('.CodeTabs_active'));
@@ -14,6 +22,21 @@ const CodeTabs = props => {
     codeblocks[index].classList.add('CodeTabs_active');
 
     target.classList.add('CodeTabs_active');
+
+    if (target.value === 'mermaid') {
+      const $openMermaid = [].slice.call($wrap.querySelectorAll('.mermaid'));
+      $openMermaid.forEach((el: Element) => el.classList.remove('mermaid'));
+      codeblocks[index].classList.add('mermaid');
+      mermaid.contentLoaded();
+    }
+  }
+
+  // render single Mermaid diagram
+  if (!Array.isArray(children) && children.props?.children.props.lang === 'mermaid') {
+    const value = children.props.children.props.value;
+    return (
+      <pre className="mermaid mermaid_single">{value}</pre>
+    )
   }
 
   return (
@@ -24,7 +47,7 @@ const CodeTabs = props => {
 
           /* istanbul ignore next */
           return (
-            <button key={i} onClick={e => handleClick(e, i)} type="button">
+            <button key={i} onClick={e => handleClick(e, i)} type="button" value={lang}>
               {meta || `${!lang ? 'Text' : uppercase(lang)}`}
             </button>
           );

diff --git a/docs/built-in-components.mdx b/docs/built-in-components.mdx
@@ -0,0 +1,37 @@
+## Built-In Components
+
+### Accordion
+
+<Accordion title="My Accordion Title" icon="fa fa-info-circle" iconColor="#018ef5">
+  Lorem ipsum dolor sit amet, **consectetur adipiscing elit.** Ut enim ad minim veniam, quis nostrud exercitation
+  ullamco. Excepteur sint occaecat cupidatat non proident!
+</Accordion>
+
+---
+
+### Cards
+
+<Cards columns={2}>
+  <Card title="First Card" href="https://readme.com" icon="fa fa-home" iconColor="#018ef5" target="_blank">
+    Neque porro quisquam est qui dolorem ipsum quia
+  </Card>
+  <Card title="Second Card" icon="fa fa-user" iconColor="#018ef5">
+    *Lorem ipsum dolor sit amet, consectetur adipiscing elit*
+  </Card>
+  <Card title="Third Card" icon="fa fa-star" iconColor="#018ef5">
+    > Ut enim ad minim veniam, quis nostrud ullamco
+  </Card>
+  <Card title="Fourth Card" icon="fa fa-question" iconColor="#018ef5">
+    **Excepteur sint occaecat cupidatat non proident**
+  </Card>
+</Cards>
+
+---
+
+### Tabs
+
+<Tabs>
+  <Tab title="First Tab">Welcome to the content that you can only see inside the first Tab.</Tab>
+  <Tab title="Second Tab">Here's content that's only inside the second Tab.</Tab>
+  <Tab title="Third Tab">Here's content that's only inside the third Tab.</Tab>
+</Tabs>
diff --git a/docs/code-blocks.md b/docs/code-blocks.md
@@ -87,6 +87,7 @@ We support syntax highlighting on a number of languages:
 | Liquid        | `liquid`                                                                             |
 | Lua           | `lua`                                                                                |
 | Markdown      | `markdown`                                                                           |
+| Mermaid       | `mermaid`                                                                            |
 | Objective-C   | `objc`, `objectivec`,                                                                |
 | Objective-C++ | `objc++`, `objcpp`, `objectivecpp`, `objectivecplusplus`,                            |
 | OCaml         | `ocaml`, `ml`                                                                        |

diff --git a/docs/mermaid.md b/docs/mermaid.md
@@ -0,0 +1,100 @@
+---
+title: 'Mermaid Diagrams'
+category: 5fdf7610134322007389a6ed
+hidden: false
+---
+
+## Examples
+
+### Single Diagram
+
+```mermaid
+    graph LR
+      A --- B
+      B-->C[fa:fa-ban forbidden]
+      B-->D(fa:fa-spinner);
+```
+
+```mermaid
+    sequenceDiagram
+        participant Alice
+        participant Bob
+        Alice->>John: Hello John, how are you?
+        loop HealthCheck
+            John->>John: Fight against hypochondria
+        end
+        Note right of John: Rational thoughts <br/>prevail!
+        John-->>Alice: Great!
+        John->>Bob: How about you?
+        Bob-->>John: Jolly good!
+```
+
+### Multiple Tabs
+
+```mermaid
+    ---
+    title: Animal example
+    ---
+    classDiagram
+        note "From Duck till Zebra"
+        Animal <|-- Duck
+        note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
+        Animal <|-- Fish
+        Animal <|-- Zebra
+        Animal : +int age
+        Animal : +String gender
+        Animal: +isMammal()
+        Animal: +mate()
+        class Duck{
+            +String beakColor
+            +swim()
+            +quack()
+        }
+        class Fish{
+            -int sizeInFeet
+            -canEat()
+        }
+        class Zebra{
+            +bool is_wild
+            +run()
+        }
+```
+```mermaid
+    stateDiagram-v2
+        [*] --> Still
+        Still --> [*]
+
+        Still --> Moving
+        Moving --> Still
+        Moving --> Crash
+        Crash --> [*]
+```
+```mermaid
+    pie title Pets adopted by volunteers
+        "Dogs" : 386
+        "Cats" : 85
+        "Rats" : 15
+```
+
+```mermaid diagram
+    journey
+        title My working day
+        section Go to work
+          Make tea: 5: Me
+          Go upstairs: 3: Me
+          Do work: 1: Me, Cat
+        section Go home
+          Go downstairs: 5: Me
+          Sit down: 5: Me
+```
+```syntax
+    journey
+        title My working day
+        section Go to work
+          Make tea: 5: Me
+          Go upstairs: 3: Me
+          Do work: 1: Me, Cat
+        section Go home
+          Go downstairs: 5: Me
+          Sit down: 5: Me
+```
diff --git a/example/docs.ts b/example/docs.ts
@@ -23,6 +23,10 @@ import lists from '../docs/lists.md';
 // @ts-ignore
 import mdxComponents from '../docs/mdx-components.mdx';
 // @ts-ignore
+import builtInComponents from '../docs/built-in-components.mdx';
+// @ts-ignore
+import mermaid from '../docs/mermaid.md';
+// @ts-ignore
 import sanitizingTests from '../docs/sanitizing-tests.md';
 // @ts-ignore
 import tableOfContentsTests from '../docs/table-of-contents-tests.md';
@@ -47,6 +51,8 @@ const fixtures = Object.entries({
   imageTests,
   lists,
   mdxComponents,
+  builtInComponents,
+  mermaid,
   sanitizingTests,
   tableOfContentsTests,
   tables,