Update to use remark-mermaidjs

[bdenham]

Description

This PR provides the following updates:

• Updates index.js to import and use remark-mermaidjs.
• Updates package.json to add remark-mermaidjs as the only dependency.
• Updates README docs to describe all the updates.

How to test this PR

1. git clone https://github.com/bdenham/mdx-starter.git
2. cd mdx-starter
3. git checkout remark-mermaidjs-test`
4. yarn install
5. yarn dev
6. Click "Mermaid MDX test page." in the browser window.
7. You should see all the same mermaid diagrams currently supported on https://mermaid.live/ rendered on this page using the mermaid base theme: Flowchart, Sequence, Gantt, Class, State, Pie Chart, Git Graph, User Journey, and Entity Relationship.
8. Compare the test page rendering of these diagrams to the https://mermaid.live/ online editor with the editor's config set to {"theme": "base"}.
9. Open the test project in your IDE and open the gatsby-config.js file.
10. Change the mermaid theme config setting to one of the other built-in mermaid themes, named and described here.
11. Open the test project in your IDE and change or add your own mermaid diagrams to the test file: src/pages/mermaid.mdx.

Other testing details

Updates to the package were manually tested in both Gatsby v4 and v5 projects:

• Gatsby v5 MDX starter project
• Gatsby v4.24 theme project

In both projects, I used yalc to test my local package changes to ensure I could successfully render the same markdown file (see below) containing all the currently supported mermaid diagrams.

Gatsby v5 MDX starter project

See instructions above to run this test.

The test markdown file was added to the Gatsby v5 starter project using both .md and .mdx extensions. All diagrams rendered correctly, matching the output shown on https://mermaid.live/. All plugin options worked as designed using the following configuration:

{
  resolve: 'gatsby-remark-mermaid',
  options: {
    language: 'mermaid',
    theme: 'base',
    viewport: {
      width: 1280,
      height: 800
    },
    mermaidOptions: {
      themeVariables: mermaidThemeVariables,
      themeCSS: mermaidThemeCSS,
      flowchart: flowchart,
    },
  },
},

Gatsby v4.24 theme project

The test markdown file was added to the Gatsby v4.24 example project within the theme's monorepo. All diagrams rendered correctly, matching the output shown on https://mermaid.live/. All plugin options worked as designed using the same configuration noted above.

Markdown Test File

MARKDOWN TEST FILE — Edit this description to copy it.

Mermaid Tests

This is a test page for mermaid diagrams.

Flowchart

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Sequence Diagrams

From Live Editor

sequenceDiagram
    Alice->>+John: Hello John, how are you?
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    John-->>-Alice: I feel great!

With loop

sequenceDiagram
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

Gantt Diagram

gantt
    dateFormat  YYYY-MM-DD
    title Adding GANTT diagram functionality to mermaid

    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2              :         des4, after des3, 5d

    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d

    section Documentation
    Describe gantt syntax               :active, a1, after des1, 3d
    Add gantt diagram to demo page      :after a1  , 20h
    Add another diagram to demo page    :doc1, after a1  , 48h

    section Last section
    Describe gantt syntax               :after doc1, 3d
    Add gantt diagram to demo page      : 20h
    Add another diagram to demo page    : 48h

Class Diagram

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age

    Animal : +String getSpecies()
    Animal : +void eat()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

State Diagram

stateDiagram
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

Pie Chart

pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5

Git Graph

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

User Journey

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

Entity Relationship Diagram

erDiagram
    CUSTOMER }|..|{ DELIVERY-ADDRESS : has
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER ||--|{ INVOICE : "liable for"
    DELIVERY-ADDRESS ||--o{ ORDER : receives
    INVOICE ||--|{ ORDER : covers
    ORDER ||--|{ ORDER-ITEM : includes
    PRODUCT-CATEGORY ||--|{ PRODUCT : contains
    PRODUCT ||--o{ ORDER-ITEM : "ordered in"

Closes #5
Closes #6
Closes #15
Closes #17

[remcohaszing]

I suggest to revamp this plugin entirely using remark-mermaidjs instead.

I think all that’s needed is the following code:

async function gatsbyRemarkMermaid(ast, options) {
  const { default: plugin } = await import('remark-mermaidjs')
  const transformer = plugin(options)
  return transformer(ast)
}

module.exports = gatsbyRemarkMermaid

Could you give that a try?

Technically the transformer takes a second argument vfile, but I’m not sure how to retrieve it from the gatsby interface and it’s unused by remark-mermaidjs.

[bdenham]

@remcohaszing: Take a look. Using remark-mermaidjs keeps this plugin pretty simple. I do have a suggestion to for updating remark-mermaidjs so we could pass in some custom viewport settings that would look something like this when configuring this plugin on the Gatsby side of things:

{
  resolve: `gatsby-remark-mermaid`,
  options: {
    launchOptions: {
      executablePath: puppeteer.executablePath(),
      defaultViewport: {
        width: 1280,
        height: 3000,
      }
    },
  }
}

[remcohaszing]

Thank you! This looks really great!

I just have a few nit picks.

[bdenham]

@remcohaszing: Great review! It's a true pleasure to work with someone who pays attention to detail!

[remcohaszing]

Awesome! Thank you! ❤️

[bdenham]

Thanks, @remcohaszing! I look forward to working with you more in the future!

[remcohaszing]

Aww thanks! I’m sure we will if you stay around in the remark / MDX ecosystem. :)