Making Plugins (`mermaid`, `datatables`) Default

[Tim-Siu]

Please confirm that you have searched existing issues in the repo

Yes, I have searched the existing issues

Any related issues?

No response

What is the area that this feature belongs to?

Performance, Plugins

Is your feature request related to a problem? Please describe.

Currently, the mermaid and datatables plugins are not activated by default. The arguments are that the performance overhead brought in is not negligible:

1. For the mermaid plugin (Add Mermaid Plugin #2475), the external javascript loaded from CDN comes in at 3.3MB and is kind of heavy. It may result in some network costs.
2. For the dataTable plugin (Add dataTable plugin #2446), the javascript involved is much lighter. The performance overhead, however, is not thoroughly investigated.

However, such a configuration is contradictory to our wishes that 'everything works out of the box'. This issue is the umbrella issue to call for investigation on the performance overhead of the plugins and efforts to make the plugins default.

Describe the solution you'd like

It is suggested by Prof. Damith that we can load the javascript libraries on demand. This is possible with modifications to the backend (site build) code.

Describe alternatives you've considered

No response

Additional context

No response

[gerteck]

Duplicated comment from #2597 as more relevant to this issue.

Some contextual knowledge for anyone reading this to better understand from quick glance: very simply,

The DataTable and Mermaid plugins work by manipulating the page after it’s been rendered by Vue.

For the DataTable plugin, it first looks for custom elements, then converts them into regular HTML tables. Based on their attributes, like sortable or searchable, it applies the necessary configuration to make them interactive using the jQuery DataTable plugin.

The Mermaid plugin operates similarly, searching for Mermaid-specific elements on the page after it’s loaded. It then uses Mermaid's rendering functions (using loaded js script) to convert those elements into diagrams.

---

I think we could consider different implementations to make this work

Alternative Implementations

Mount Multiple Vue instance for each Mermaid Element

This is alternative to attaching the directive to parent app Vue instance. Initializing a new vue instance for each Mermaid diagram, registering the mermaid directive for that specific instance.
Ensures that each diagram has its own scoped configuration and avoids issues with Vue 3's global app instance limitations. However, this could lead to performance overhead if many Mermaid diagrams are rendered on a page.

Direct Mutation of Mermaid Elements

Directly mutate Mermaid elements outside of Vue’s reactive. Could involve simply manipulating the DOM and invoking Mermaid’s rendering functions manually on element. Since the script runs after html is hydrated by Vue on client side.

Plugin vs. Default Features

Making it a plugin vs. default feature: I think if we make it default there are definitely size and performance impacts, thank you for pointing it out, overlooked this crucial aspect.

Considering this, I think it definitely makes sense to keep these features as plugins.

Difference in size / performance

A quick test on markbind.org shows
(dev tools -> sources -> plugins/dataTable/datatables.min.js || mermaid-5a5980d4.js)

• mermaid.js file to be at 322kb,
• datatable.js + css file at 192kb

which is actually quite hefty. E.g. if you load markbind.org, you need to load (~0.5 mb) of just the plugin js scripts. In fact, right now, even if you don't have any datatable or mermaid on the current page you need to load these script, as long as you enabled the plugins¹.

If we continue this approach, providing mermaid offline support just mean to bundle it as needed as done with DataTable.

One quick way I can think of is that perhaps we can provide a toggle through plugin context to toggle between offline support and online support - what do you think?

Side Note

¹ I just realized there is potential for easy quick efficiency fix to current mermaid plugin - if no mermaid elements then we don't load mermaid script, because now it indiscriminately loads mermaid script on every page on load, if plugin is enabled @Tim-Siu . I can make a quick PR (#2614) to demonstrate what I mean.