Add four missing diagrams, provide contributor instructions, and upda…

…te mermaid. (#53) * Adds mindmap to supported diagrams. Adds example techdocs. Adds contributor notes. * Adds more examples to sample. * Bump upstream mermaid version. Expand sample docs to provide more context around each example. * Katex Example. * Updates package version. Update yarn.lock. * Revert manual version bump and instructions related to submitting a new PR. --------- Co-authored-by: Justin Treher <jtreher@webstaurantstore.com>
johanneswuerbach · Aug 23, 2024 · b6dd21e · b6dd21e
1 parent bed9ef3
commit b6dd21e
Show file tree

Hide file tree

Showing 7 changed files with 339 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -50,7 +50,7 @@ graph TD;
 
 ## Auto-Detection vs. Manual Detection
 
-By default, this plugin will autodetect diagrams based on the starting token of the code block. In some cases, however, this auto-detection is not sufficient, for example because of an unrecognized 
+By default, this plugin will autodetect diagrams based on the starting token of the code block. In some cases, however, this auto-detection is not sufficient, for example, because of an unrecognized 
 diagram type or the use of front matter. In these cases, you can force the use of mermaid on blocks by adding configuration like this to your `mkdocs.yaml` file:
 
 ```yaml
@@ -61,4 +61,42 @@ markdown_extensions:
         - name: mermaid
           class: mermaid
           format: !!python/name:pymdownx.superfences.fence_code_format
-```
+```
+
+## Contributors Guide
+
+This plugin can be developed in the context of an existing Backstage deployment or a [new local deployment](https://backstage.io/docs/getting-started/#1-create-your-backstage-app).
+
+### Setup for Deployment
+
+1. Fork and clone this repo into the plugins folder of your Backstage codebase.
+2. To have yarn link the local version of the addon instead of the version on npm.
+  1. Change directories to the new `plugins/backstage-plugin-techdocs-addon-mermaid folder` and run `yarn link`.
+  2. Go up to the main Backstage directory and run `yarn link "backstage-plugin-techdocs-addon-mermaid`.
+3. Run `yarn install` in the Backstage root.
+4. Follow the earlier instructions to add the plugin to your TechDocs pages in your Backstage deployment such as `app.tsx`.
+
+### Manual Testing
+
+After making changes to the plugin and having unit tests pass, to do manual end-to-end testing, follow the instructions below.
+
+#### Option #1 Techdocs CLI
+
+You can use the [TechDocs CLI](https://backstage.io/docs/features/techdocs/cli/) to test against a local docs folder. You will need to customize the preview app bundle for that to work as the addon is not included in the [standard bundle](https://github.com/backstage/techdocs-cli/blob/main/packages/embedded-techdocs-app/src/App.tsx). Review the TechDoc's documentation for further instructions.
+
+#### Option #2 Use a Remote Location
+
+Register a component via URL like any other Backstage component and view that component's TechDocs. 
+For example, to use the SampleDocs component in this repo:
+
+1. Generate a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for *public repos*.
+2. Add the [GitHub integration](https://backstage.io/docs/integrations/github/locations) to your `app-config.local.yaml`.
+3. `yarn dev` in the root of your Backstage codebase.
+4. To register the demo docs, browse to `http://localhost:3000/catalog-import`
+5. Register the URL pointing to the SampleDocs/catalog-info.yaml, example: `https://github.com/johanneswuerbach/backstage-plugin-techdocs-addon-mermaid/blob/main/sampledocs/catalog-info.yaml`
+6. To iterate:
+   1. Create a branch for the addon.
+   2. Change the contents of the sampledocs.
+   3. Commit and push.
+   4. Register the catalog-info.yaml for your branch instead (keep in mind any security changes required for your personal access token).
+   5. Iterate changes to markdown and changes to the plugin.
diff --git a/package.json b/package.json
@@ -34,7 +34,7 @@
     "@material-ui/core": "^4.12.2",
     "@material-ui/icons": "^4.11.3",
     "@material-ui/lab": "4.0.0-alpha.61",
-    "mermaid": "^10.3.0",
+    "mermaid": "^10.9.1",
     "react-use": "^17.2.4"
   },
   "peerDependencies": {

diff --git a/sampledocs/catalog-info.yaml b/sampledocs/catalog-info.yaml
@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: sampledocs
+  annotations:
+    backstage.io/techdocs-ref: dir:.
+spec:
+  type: documentation
+  lifecycle: production
+  owner: you
diff --git a/sampledocs/docs/index.md b/sampledocs/docs/index.md
@@ -0,0 +1,238 @@
+# Example Supported Mermaid Diagrams
+
+## Supported by the Add On
+
+## Graph/Flowchart
+
+```mermaid
+graph TD
+    A[Start] --> B{Is it working?}
+    B -- Yes --> C[Continue]
+    B -- No --> D[Fix it]
+    D --> B
+    C --> E[Finish]
+```
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>Bob: Hello Bob, how are you?
+    Bob-->>Alice: I'm good thanks!
+    Alice->>Bob: Great to hear
+```
+
+### Gantt
+
+```mermaid
+gantt
+    title A Gantt Diagram
+    dateFormat  YYYY-MM-DD
+    section Section
+    Task 1           :a1, 2023-01-01, 30d
+    Task 2           :after a1  , 20d
+    Task 3           : 2023-02-11  , 20d
+    Task 4           : 2023-02-21  , 20d
+```
+
+### Class Diagram
+
+```mermaid
+classDiagram
+    class Animal {
+      +String species
+      +void eat()
+    }
+    class Dog {
+      +String breed
+      +void bark()
+    }
+    Animal <|-- Dog
+```
+
+### State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Working : start
+    Working --> Idle : stop
+    Working --> Failed : error
+```
+
+### Pie
+
+```mermaid
+pie
+    title Language Popularity
+    "JavaScript" : 50
+    "Python" : 25
+    "Java" : 15
+    "C++" : 10
+```
+
+### erDiagram
+
+```mermaid
+erDiagram
+    CUSTOMER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+```
+
+### Journey
+
+```mermaid
+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
+```
+
+### Quadrant Chart
+
+```mermaid
+quadrantChart
+    title Reach and engagement of campaigns
+    x-axis Low Reach --> High Reach
+    y-axis Low Engagement --> High Engagement
+    quadrant-1 We should expand
+    quadrant-2 Need to promote
+    quadrant-3 Re-evaluate
+    quadrant-4 May be improved
+    Campaign A: [0.3, 0.6]
+    Campaign B: [0.45, 0.23]
+    Campaign C: [0.57, 0.69]
+    Campaign D: [0.78, 0.34]
+    Campaign E: [0.40, 0.34]
+    Campaign F: [0.35, 0.78]
+```
+
+### Requirement Diagram
+
+```mermaid
+requirementDiagram
+
+    requirement test_req {
+    id: 1
+    text: the test text.
+    risk: high
+    verifymethod: test
+    }
+
+    element test_entity {
+    type: simulation
+    }
+
+    test_entity - satisfies -> test_req
+```
+
+### GitGraph
+
+```mermaid
+gitGraph
+   commit
+   commit
+   branch develop
+   checkout develop
+   commit
+   commit
+   checkout main
+   merge develop
+   commit
+   commit
+```
+
+### MindMap
+
+```mermaid
+mindmap
+  root((mindmap))
+    Origins
+      Long history
+      ::icon(fa fa-book)
+      Popularisation
+        British popular psychology author Tony Buzan
+    Research
+      On effectiveness<br/>and features
+      On Automatic creation
+        Uses
+            Creative techniques
+            Strategic planning
+            Argument mapping
+    Tools
+      Pen and paper
+      Mermaid
+```
+
+### Timeline
+
+```mermaid
+timeline
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook
+         : Google
+    2005 : Youtube
+    2006 : Twitter
+```
+
+### XYChart-Beta
+
+```mermaid
+xychart-beta
+    title "Sales Revenue"
+    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
+    y-axis "Revenue (in $)" 4000 --> 11000
+    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+```
+
+### Block Beta
+
+```mermaid
+block-beta
+columns 1
+  db(("DB"))
+  blockArrowId6<["&nbsp;&nbsp;&nbsp;"]>(down)
+  block:ID
+    A
+    B["A wide one in the middle"]
+    C
+  end
+  space
+  D
+  ID --> D
+  C --> D
+  style B fill:#969,stroke:#333,stroke-width:4px
+```
+
+### Katex
+
+```mermaid
+graph LR
+    A["$$f(\relax{x}) = \int_{-\infty}^\infty \hat{f}(\xi)\,e^{2 \pi i \xi x}\,d\xi$$"] -->|"$$\Bigg(\bigg(\Big(\big((\frac{-b\pm\sqrt{b^2-4ac}}{2a})\big)\Big)\bigg)\Bigg)$$"| B("$$1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\cdots}}}}$$")
+    A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\phase{-78^\circ}$$")
+    B --> D("$$x = \begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$$")
+    C --> E("$$x(t)=c_1\begin{bmatrix}-\cos{t}+\sin{t}\\ 2\cos{t} \end{bmatrix}e^{2t}$$")
+```
+
+## Not yet supported
+
+### ZenUml
+
+```mermaid
+zenuml
+    title Demo
+    Alice->John: Hello John, how are you?
+    John->Alice: Great!
+    Alice->John: See you later!
+```
+
diff --git a/src/Mermaid/hooks.test.ts b/src/Mermaid/hooks.test.ts
@@ -18,6 +18,38 @@ describe("isMermaidCode", () => {
       expect(result).toBe(true);
     });
 
+    it("Mindmap mermaid code exists", () => {
+      const mermaidCode = "mindmap root((foo bar)) Baz";
+
+      const result = isMermaidCode(mermaidCode);
+
+      expect(result).toBe(true);
+    });
+
+    it("Quadrant chart mermaid code exists", () => {
+      const mermaidCode = "quadrantChart x-axis Low Reach --> High Reach";
+
+      const result = isMermaidCode(mermaidCode);
+
+      expect(result).toBe(true);
+    });
+
+    it("xychart-beta chart mermaid code exists", () => {
+      const mermaidCode = "xychart-beta x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]";
+
+      const result = isMermaidCode(mermaidCode);
+
+      expect(result).toBe(true);
+    });
+
+    it("Block-beta chart mermaid code exists", () => {
+      const mermaidCode = "block-beta columns 1 db((\"DB\"))";
+
+      const result = isMermaidCode(mermaidCode);
+
+      expect(result).toBe(true);
+    });
+
     it("C4Container mermaid code exists", () => {
       const mermaidCode = "C4Container foo foo2 foo-->foo2";
 

diff --git a/src/Mermaid/hooks.ts b/src/Mermaid/hooks.ts
@@ -15,7 +15,7 @@
  */
 
 const mermaidStart =
-  /^(\s*)(graph|flowchart|sequenceDiagram|classDiagram|stateDiagram|erDiagram|journey|gantt|pie|requirementDiagram|gitGraph|C4Context|C4Container|C4Component|C4Dynamic|C4Deployment|timeline)/gm;
+  /^(\s*)(graph|flowchart|sequenceDiagram|classDiagram|stateDiagram|erDiagram|journey|gantt|pie|requirementDiagram|gitGraph|C4Context|C4Container|C4Component|C4Dynamic|C4Deployment|timeline|mindmap|quadrantChart|xychart-beta|block-beta)/gm;
 
 export const isMermaidCode = (code: string): boolean => {
   if (code.startsWith('%%{init')) {