feat(mermaid): Add Mermaid.js diagrams plugin

[cloudjumpercat]

The docs team recently added Mermaid.js to our own docs repo (see PR here) to make it easy to create diagrams. We also added some custom styles to match our branding colors. I thought it would make a nice addition to the Kuma repo, and I have a doc that I'm writing that would benefit from this diagram tool.

It can be used with the following syntax:

{% mermaid %}
{% endmermaid %}

With mermaid we can describe graphs and diagrams in a markdown file and have them render as what we want.
So

{% mermaid %}
gantt
   title Git Issues - days since last update
   dateFormat  X
   axisFormat %s

   section Issue19062
   71   : 0, 71
   section Issue19401
   36   : 0, 36
   section Issue193
   34   : 0, 34
   section Issue7441
   9    : 0, 9
   section Issue1300
   5    : 0, 5
{% endmermaid %}

would render as:

We've been using https://mermaid.live/edit to easily generate diagrams and see the rendered output before adding it to docs.

Did you sign your commit? Instructions Yes

Have you read Contributing guidelines? Yes

[netlify]

✅ Deploy Preview for kuma ready!

Name	Link
🔨 Latest commit	e7ddd55
🔍 Latest deploy log	https://app.netlify.com/sites/kuma/deploys/65afd0368d0e070008745b6b
😎 Deploy Preview	https://deploy-preview-1547--kuma.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[cloudjumpercat]

The docs team added this to our stylesheet: https://github.com/Kong/docs.konghq.com/blob/e2f6df6b7f639891c59aad47b54ffe83c752c94b/app/_assets/stylesheets/page.less#L346

But I wasn't sure where to put that in the kuma-website style sheet.

[cloudjumpercat]

I need to delete this edit before this PR is merged, but here's an example of how a flowchart would currently render in the Kuma docs: https://deploy-preview-1547--kuma.netlify.app/docs/2.5.x/introduction/about-service-meshes/

[lena-larionova]

I think you should be able to set it here, to fix the styling:
https://github.com/cloudjumpercat/kuma-website/blob/feat/mermaid-js/app/_assets/styles/custom/base/_type-and-content.scss#L89-L98C6

This should work:

  pre,
  pre[class*='language-'],
  div[class*='language-'] {
    background-color: $codeBgColor;

    &.mermaid {
      background-color: unset;
    }

    code {
      font-size: 0.9rem;
      line-height: 1.5;
      color: #333;
    }
  }

If that doesn't work, then you can do it like this:

  pre,
  pre[class*='language-'],
  div[class*='language-'] {
    background-color: $codeBgColor;

    code {
      font-size: 0.9rem;
      line-height: 1.5;
      color: #333;
    }
  }

 pre.mermaid {
      background-color: unset;
  }

[cloudjumpercat]

@lena-larionova Thanks for the feedback! You're first suggestion fixed it!

[cloudjumpercat]

I removed the test example so I can mark this PR as ready, but here's an image of what it looked like when rendered:

[slonka]

Hi! :) We already have some diagrams like this one

and a policy to make the diagrams

kuma-website/WRITING-DOCUMENTATION.md

Line 28 in 58bbbac

The team is moving diagrams to [Google slides](https://docs.google.com/presentation/d/1qvIKeYfcuowrHW1hV9fk9mCptt3ywroPBUYFjMj9gkk/edit#slide=id.g13d0c1ffb72_0_67).

( https://docs.google.com/presentation/d/1qvIKeYfcuowrHW1hV9fk9mCptt3ywroPBUYFjMj9gkk/edit#slide=id.g13d0c1ffb72_0_67 ). I don't think we should have two ways of making diagrams and I don't think it's worth going through all of them and converting them to mermaid.

Added @lahabana to reviewers so he can take a look at this.

[lahabana]

I think this is very welcome! Lowering the bar of adding graph and charts is a great idea!
However, should plugins like this be extracted away to be consumable as a dependency? this duplication seems to be the open door to future maintainance issues.

Can we start using it somewhere? I think it'd make it easier to review :)

Also is it ok to rely on a CDN for the mermaid lib?

@fabianrbz WDYT?

[fabianrbz]

I think this is very welcome! Lowering the bar of adding graph and charts is a great idea! However, should plugins like this be extracted away to be consumable as a dependency? this duplication seems to be the open door to future maintainance issues.

We can, however, we wouldn't be gaining much tbh.

Can we start using it somewhere? I think it'd make it easier to review :)

We have a few examples in docs.konghq

Also is it ok to rely on a CDN for the mermaid lib?

It should be ok, it's what they use in their docs.

@fabianrbz WDYT?

It's the same implementation we have in docs.konghq, I'm trying to improve it so that the script doesn't get included with every diagram (we could have several diagrams on one page). I also don't want to include the mermaid js on every page.
I'll get back to you on this

[lahabana]

@cloudjumpercat can you rebase you first commit so it's Signed-Off too? (or just squash all your commits).

[cloudjumpercat]

@bartsmykla I squashed and signed the commit, but I'm not sure if it worked correctly since it seems to have brought in changes to the master branch. I used the following to squash it:

git reset --soft master
git commit -m "Add Mermaid diagrams" --signoff
git push origin feat/mermaid-js --force

[bartsmykla]

@cloudjumpercat all looks good now, thank you!