Add Mermaid Plugin #2475

Tim-Siu · 2024-03-25T15:48:37Z

What is the purpose of this pull request?

Overview of changes:
Related to #2052
Related to #1663 for pie-chart
Related to #984 for diagramming tool

This pull request is a continuation of the work done in the previously closed pull request #2052. It builds upon the changes and addresses the diagrams not rendered inside Vue components issue.

I would like to acknowledge and give credit to the original author, @tlylt , for his initial contribution and efforts in the closed pull request. Their work laid the foundation for the changes proposed in this new pull request.

Some changes include:

Upgrade the usage of Mermaid to v10.
Migrate JavaScript to TypeScript.
Drop the configuration customization as it seems no longer relevant (given loading issues are solved)

Please review the changes and provide any further feedback or suggestions for improvement. Thank you!

Anything you'd like to highlight/discuss:

function genScript(address: string) {
  return `<script type="module">
    import mermaid from '${address || DEFAULT_CDN_ADDRESS}';
    document.addEventListener('DOMContentLoaded', () => {
      Vue.directive('mermaid', {
        inserted: function(el) {
          mermaid.run({
            nodes: [el]
          });
        }
      });
    });
  </script>`;
}

Based on my ''ablation studies'', it seems like that importing the script will results in automatic initialization (for diagrams outside of Vue components) and the Vue directive will initialize the diagrams inside Vue components.

Testing instructions:

Proposed commit message: (wrap lines at 72 characters)

Support Mermaid

Checklist: ☑️

Updated the documentation for feature additions and enhancements
Added tests for bug fixes or features
Linked all related issues
No unrelated changes

Reviewer checklist:

Indicate the SEMVER impact of the PR:

Major (when you make incompatible API changes)
Minor (when you add functionality in a backward compatible manner)
Patch (when you make backward compatible bug fixes)

At the end of the review, please label the PR with the appropriate label: r.Major, r.Minor, r.Patch.

Breaking change release note preparation (if applicable):

To be included in the release note for any feature that is made obsolete/breaking

Give a brief explanation note about:

what was the old feature that was made obsolete

any replacement feature (if any), and

how the author should modify his website to migrate from the old feature to the replacement feature (if possible).

codecov · 2024-03-25T15:52:30Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 50.91%. Comparing base (c9f72c4) to head (3186303).

❗ Current head 3186303 differs from pull request most recent head c6c869b. Consider uploading reports for the commit c6c869b to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2475      +/-   ##
==========================================
- Coverage   51.05%   50.91%   -0.14%     
==========================================
  Files         126      126              
  Lines        5467     5450      -17     
  Branches     1174     1171       -3     
==========================================
- Hits         2791     2775      -16     
+ Misses       2381     2380       -1     
  Partials      295      295

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

kaixin-hc · 2024-04-03T10:20:33Z

Nice work! It looks good and the documentation is clear - though I'd like to play around with it a little more before approving

I am wondering if we should have it be a separate test site, as this is also a plugin similar to algolia and the like. We should probably come to a decision and then include this in the developer guide for guidance

packages/core/src/plugins/mermaid.ts

EltonGohJH · 2024-04-04T11:16:02Z

I think implementation look good to me. Just like Hannah, I need more time to play around and test it!

yucheng11122017

Ok the mermaid website is broken so I can't test it but some nits about documentation first!

docs/userGuide/plugins/mermaid.md

yucheng11122017 · 2024-04-04T12:04:22Z

docs/userGuide/plugins/mermaid.md

@@ -0,0 +1,96 @@
+### Plugin: Mermaid
+
+This plugin allows you to utilize <tooltip content="Mermaid lets you create diagrams and visualizations using text and code">Mermaid</tooltip> by automatically importing the library and initializing the rendering of the diagrams.


I think linking to the Mermaid documentation here is better than using a tool tip

Somewhat agree but I really liked the effect of the tooltip as well. Maybe at the bit where we talk about external plugins, we can add tooltips to the documentation

The tooltip has been removed. Looking for more advice.

yucheng11122017

Hi @Tim-Siu thanks for the PR! The test site doesn't seem to be working... could you check?

docs/userGuide/syntax/diagrams.md

packages/cli/test/functional/test_site/testMermaid.md

yucheng11122017

Some nits and improvements on test case! This looks great the mermaid diagrams look really awesome

yucheng11122017 · 2024-04-16T15:22:38Z

packages/cli/test/functional/test_site/testMermaid.md

@@ -0,0 +1,71 @@
+**Mermaid Test**


Could we add a functional test to make sure that mermaid works when using include?

Currently, the mermaid plugin loads after the two internal and external plugin we have on the test site, so it will like this at first..

Currently, the mermaid plugin loads after the two internal and external plugin we have on the test site, so it will like this at first..

Thanks for the investigation!

Sorry, I mistook it for a unit test and was thinking about how to achieve this. Thank you for your reminder!

docs/userGuide/syntax/diagrams.md

docs/userGuide/plugins/mermaid.md

EltonGohJH · 2024-04-17T03:17:01Z

LGTM. I think the implementation is good.
I think should be good to merge after you resolve all the comments pointed out by @yucheng11122017 .

yucheng11122017

Some nits! Also @Tim-Siu when modifying all your PRs could you please make sure that you address all the comments on the review? If you disagree with it, you can reply on why you disagree rather than leaving it.

docs/userGuide/plugins/mermaid.md

docs/userGuide/syntax/diagrams.md

packages/cli/test/functional/test_site/testMermaid.md

@@ -0,0 +1,71 @@
+**Mermaid Test**


Tim-Siu · 2024-04-21T06:25:13Z

Some nits! Also @Tim-Siu when modifying all your PRs could you please make sure that you address all the comments on the review? If you disagree with it, you can reply on why you disagree rather than leaving it.

Sorry for the confusion, I will keep clearer communications next time.

yucheng11122017

One comment and i think should be good!

packages/cli/test/functional/test_site/testMermaid.md

yucheng11122017

Some comments

yucheng11122017 · 2024-04-22T03:45:29Z

docs/userGuide/usingPlugins.md

@@ -65,6 +65,8 @@ MarkBind has a set of built-in plugins that can be used immediately without inst
 <include src="plugins/mathDelimiters.md" />
 <include src="plugins/web3Form.md" />
 <include src="plugins/dataTable.md" />
+<include src="plugins/mermaid.md" />
+


unnecessary new line

yucheng11122017 · 2024-04-22T03:45:47Z

packages/cli/test/functional/test_site/testMermaid.md

+
+<include src="testMermaidFragment.md" />
+
+<panel type="minimal" header="This is to test Mermaid diagrams works when included inside a panel." src="testMermaidFragment.md">


Suggested change

<panel type="minimal" header="This is to test Mermaid diagrams works when included inside a panel." src="testMermaidFragment.md">

<panel type="minimal" header="This is to test Mermaid diagrams works when included inside a panel." src="testMermaidFragment.md"/>

yucheng11122017 · 2024-04-22T03:46:15Z

packages/cli/test/functional/test_site/testMermaidFragment.md

Don't use the word fragment here because include fragment means like a partial include

yucheng11122017

LGTM!

damithc · 2024-04-24T03:42:51Z

@Tim-Siu Good work on adding this. While we are on this topic, is there a reason (e.g., performance cost) for not enabling this plugin (and the data table plugin) by default? Normally, we want to make 'everything works out of the box' (i.e., requires minimal configuration by the user.

Tim-Siu · 2024-04-24T03:51:21Z

@Tim-Siu Good work on adding this. While we are on this topic, is there a reason (e.g., performance cost) for not enabling this plugin (and the data table plugin) by default? Normally, we want to make 'everything works out of the box' (i.e., requires minimal configuration by the user.

Hi @damithc ,

For the mermaid plugin, the external javascript loaded from CDN comes in at 3.3MB and is kind of heavy. It may results in some network costs.

For the dataTable plugin, the javascript involved is much lighter. I have not systematically determined the performance overhead though.

damithc · 2024-04-24T03:56:24Z

For the mermaid plugin, the external javascript loaded from CDN comes in at 3.3MB and is kind of heavy. It may results in some network costs.

For the dataTable plugin, the javascript involved is much lighter. I have not systematically determined the performance overhead though.

@Tim-Siu I see. Is an 'enable by default, but don't load if not used' approach feasible?

Tim-Siu · 2024-04-24T04:01:24Z

For the mermaid plugin, the external javascript loaded from CDN comes in at 3.3MB and is kind of heavy. It may results in some network costs.
For the dataTable plugin, the javascript involved is much lighter. I have not systematically determined the performance overhead though.

@Tim-Siu I see. Is an 'enable by default, but don't load if not used' approach feasible?

I think it is possible to achieve this in the page build stage. I can do some research and work on it after the exams.

damithc · 2024-04-24T04:24:47Z

I think it is possible to achieve this in the page build stage. I can do some research and work on it after the exams.

@Tim-Siu I see. Perhaps, something to try in future. Perhaps create an issue for it now so that we keep it in view?

Tim-Siu · 2024-04-24T04:25:48Z

I think it is possible to achieve this in the page build stage. I can do some research and work on it after the exams.

@Tim-Siu I see. Perhaps, something to try in future. Perhaps create an issue for it now so that we keep it in view?

Sure!

Co-authored-by: Tim-Siu <shuyao@u.nus.edu> Co-authored-by: yucheng2207 <e0560244@u.nus.edu> Co-authored-by: david <71922282+itsyme@users.noreply.github.com>

damithc · 2024-05-03T11:17:44Z

Feature in action: https://nus-cs2103-ay2324s2.github.io/website/schedule/week3/project.html

https://nus-cs2103-ay2324s2.github.io/website/admin/gradeBreakdown.html

Tim-Siu added 3 commits March 25, 2024 20:40

Add mermaid plugin

a9a873b

Improve code quality

a22da8e

Improve code quality

968378b

Tim-Siu added 2 commits April 1, 2024 12:19

Merge branch 'master' into mermaid

a818c5c

Add unit test

5baf061

Tim-Siu marked this pull request as ready for review April 1, 2024 04:46

Tim-Siu added 4 commits April 1, 2024 12:56

Add functional test

1d48418

Add documentation

3b19e31

Enhance functional test with inside panel option

1f9a752

Update test expected

6358354

EltonGohJH reviewed Apr 4, 2024

View reviewed changes

packages/core/src/plugins/mermaid.ts Show resolved Hide resolved

yucheng11122017 reviewed Apr 4, 2024

View reviewed changes

yucheng11122017 mentioned this pull request Apr 4, 2024

Add pagefind #2477

Draft

14 tasks

Tim-Siu added 2 commits April 5, 2024 09:44

Merge branch 'master' into mermaid

fa53f12

Improve documentation

e7d6d4d

yucheng11122017 force-pushed the master branch 2 times, most recently from cb84513 to 69ec838 Compare April 5, 2024 06:21

yucheng11122017 reviewed Apr 12, 2024

View reviewed changes

docs/userGuide/syntax/diagrams.md Outdated Show resolved Hide resolved

packages/cli/test/functional/test_site/testMermaid.md Show resolved Hide resolved

Tim-Siu and others added 6 commits April 13, 2024 01:41

Merge master

fb21d00

Fix code issues

6658892

Update functional code

713a4d1

Update unit test

0736424

Merge branch 'master' into mermaid

c2fa86c

Merge branch 'master' into mermaid

edc199a

yucheng11122017 reviewed Apr 16, 2024

View reviewed changes

Merge branch 'master' into mermaid

c4bfb0c

Tim-Siu added 3 commits April 19, 2024 16:44

Revert async loading of mermaid script

1d3cf98

Update functional test

a63d674

Update functional test

fc6da44

yucheng11122017 reviewed Apr 21, 2024

View reviewed changes

docs/userGuide/plugins/mermaid.md Outdated Show resolved Hide resolved

docs/userGuide/syntax/diagrams.md Outdated Show resolved Hide resolved

packages/cli/test/functional/test_site/testMermaid.md

@@ -0,0 +1,71 @@

**Mermaid Test**

This comment was marked as resolved.

Sign in to view

Tim-Siu added 3 commits April 21, 2024 14:43

Improve documentation

f5d0c0a

Enhance functional test to cover inclusion

c0a1488

Update expected

3186303

yucheng11122017 reviewed Apr 21, 2024

View reviewed changes

packages/cli/test/functional/test_site/testMermaid.md Outdated Show resolved Hide resolved

Tim-Siu and others added 5 commits April 21, 2024 22:50

Minor update to syntax

3265bb7

Update functional test

6df7858

Merge branch 'master' into mermaid

fd2c69c

Fix typo

2bf16fe

Fix typo

ca91a02

yucheng11122017 reviewed Apr 22, 2024

View reviewed changes

yucheng11122017 added 2 commits April 22, 2024 11:46

Fix nits

392b756

fix nits

c6c869b

yucheng11122017 approved these changes Apr 22, 2024

View reviewed changes

yucheng11122017 merged commit 004e7d2 into MarkBind:master Apr 24, 2024
8 checks passed

github-actions bot added the r.Minor Version resolver: increment by 0.1.0 label Apr 24, 2024

This was referenced Apr 24, 2024

Making Plugins (mermaid, datatables) Default #2529

Open

Add Mermaid Plugin (Re-PR) #2531

Merged

itsyme added a commit that referenced this pull request Apr 24, 2024

Support Mermaid (#2475)

f448b73

Co-authored-by: Tim-Siu <shuyao@u.nus.edu> Co-authored-by: yucheng2207 <e0560244@u.nus.edu> Co-authored-by: david <71922282+itsyme@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Mermaid Plugin #2475

Add Mermaid Plugin #2475

Tim-Siu commented Mar 25, 2024 •

edited by yucheng11122017

codecov bot commented Mar 25, 2024 •

edited

kaixin-hc commented Apr 3, 2024

EltonGohJH commented Apr 4, 2024

yucheng11122017 left a comment

yucheng11122017 Apr 4, 2024

kaixin-hc Apr 6, 2024

Tim-Siu Apr 21, 2024

yucheng11122017 left a comment

yucheng11122017 left a comment

yucheng11122017 Apr 16, 2024

yucheng11122017 Apr 16, 2024

Tim-Siu Apr 16, 2024

This comment was marked as resolved.

Tim-Siu Apr 21, 2024

EltonGohJH commented Apr 17, 2024

yucheng11122017 left a comment

This comment was marked as resolved.

Tim-Siu commented Apr 21, 2024

yucheng11122017 left a comment

yucheng11122017 left a comment

yucheng11122017 Apr 22, 2024

yucheng11122017 Apr 22, 2024

yucheng11122017 Apr 22, 2024

yucheng11122017 left a comment

damithc commented Apr 24, 2024

Tim-Siu commented Apr 24, 2024

damithc commented Apr 24, 2024

Tim-Siu commented Apr 24, 2024 •

edited

damithc commented Apr 24, 2024

Tim-Siu commented Apr 24, 2024

damithc commented May 3, 2024

		@@ -0,0 +1,96 @@
		### Plugin: Mermaid

		This plugin allows you to utilize <tooltip content="Mermaid lets you create diagrams and visualizations using text and code">Mermaid</tooltip> by automatically importing the library and initializing the rendering of the diagrams.


		<include src="testMermaidFragment.md" />

		<panel type="minimal" header="This is to test Mermaid diagrams works when included inside a panel." src="testMermaidFragment.md">

Add Mermaid Plugin #2475

Add Mermaid Plugin #2475

Conversation

Tim-Siu commented Mar 25, 2024 • edited by yucheng11122017

codecov bot commented Mar 25, 2024 • edited

Codecov Report

kaixin-hc commented Apr 3, 2024

EltonGohJH commented Apr 4, 2024

yucheng11122017 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yucheng11122017 left a comment

Choose a reason for hiding this comment

yucheng11122017 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as resolved.

Choose a reason for hiding this comment

EltonGohJH commented Apr 17, 2024

yucheng11122017 left a comment

Choose a reason for hiding this comment

This comment was marked as resolved.

Tim-Siu commented Apr 21, 2024

yucheng11122017 left a comment

Choose a reason for hiding this comment

yucheng11122017 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yucheng11122017 left a comment

Choose a reason for hiding this comment

damithc commented Apr 24, 2024

Tim-Siu commented Apr 24, 2024

damithc commented Apr 24, 2024

Tim-Siu commented Apr 24, 2024 • edited

damithc commented Apr 24, 2024

Tim-Siu commented Apr 24, 2024

damithc commented May 3, 2024

Tim-Siu commented Mar 25, 2024 •

edited by yucheng11122017

codecov bot commented Mar 25, 2024 •

edited

Tim-Siu commented Apr 24, 2024 •

edited