just-the-docs
Mermaid slowing down PageInsights score
Is your feature request related to a problem? Please describe. The PageInsights score, particularly for mobile, is negatively impacted by mermaid.
Describe the solution you'd like Under "Eliminate render-blocking resources", Google PageInsights indicates that mermaid.min.js has a transfer size of 265.1 KiB and can have a potential savings of 2,130 ms.
| Platform | PageInsights Score | Transfer Size | Potential Savings |
|---|---|---|---|
| Mobile | 65 | 265.1 KiB | 2,130 ms |
| Desktop | 96 | 265.1 KiB | 470 ms |
More from Google on render blocking resources: https://web.dev/render-blocking-resources/
Describe alternatives you've considered This is an enhancement; the site works "just fine" as-is. No alternatives considered.
Additional context I am not an expert on mermaid at all. I am just passing along what I see as the main reported issue from Google. Ideally, mermaid could be enhanced somehow to speed up the website.
First re-run the tests by disabling mermaid from _config.yml
Then in my opinion the problem is not that, but rather that the scripts are in the header and therefore they are blocked, mind if they are in the body at the end they are not, however I am investigating this problem as well. Moving the scripts to the end breaks some parts of the code.
Commenting out those lines in config fixed this issue; thanks @simonebortolin! I can leave it as-is and this issue can be marked as resolved, but ideally the code can be skipped unless mermaid is used.
Just to chime in @SamsungGalaxyPlayer - mermaid is disabled by default (if you consume the theme as a remote theme / gem), precisely for this reason. Are you copying the _config.yml from our main repo? Perhaps we can improve our documentation here.
When a site enables mermaid, the code gets loaded when any page on the site is visited. But it could be that mermaid is actually needed only on some infrequently visited page(s), so its loading is mostly useless.
However, I think it would be possible to add a site configuration option (say mermaid.page: true) to load the code only on pages that request it (e.g., by setting mermaid: true).
Would that improve the PageInsights score of the theme doc pages?
@pdmosses Yes, I believe so. An exception to this could be if mermaid was needed on the "home" page, but that's unavoidable.
Okay, coming back to this now - I think I'm missing some context. @SamsungGalaxyPlayer, it sounds like for the site you're benchmarking against, you're not using mermaid, but you've copied over the config provided in this repo (opposed to creating your own) and/or forked the repo itself. Is that correct? Or, are you benchmarking our docs site itself?
In general, I don't think it is a good idea for consumers of our theme to exactly copy our _config.yml; instead, using our template repo or consuming the theme via gem, etc. would make more sense. I think the core problem here is that we need to improve this workflow - we intentionally made mermaid opt-in (since I think only a small portion of our users would use it), but it seems like that's getting circumvented via copying.
On some separate notes (that in my opinion, are not directly related to the cited problem):
- we should be able to load the mermaid code at the end of
<body>; I don't see why it needs to be loaded in the<head>, as long as the load completes before our own initialization code executes. - per-page
mermaidloading seems overkill for this feature; from my understanding of browser behaviour, it'll be cached across the site itself (not other sites) after the first load anyways
Going to close this for now. Feel free to re-open if you have additional comments!
- per-page
mermaidloading seems overkill for this feature; from my understanding of browser behaviour, it'll be cached across the site itself (not other sites) after the first load anyways
But look at our site: we only use mermaid on one page. Currently, anyone landing on the rest of our site loads mermaid – regardless of whether they ever visit the page where it's used.
I guess the same will happen on most sites that activate mermaid site-wide.
I think this issue can easily be fixed in a non-breaking way after v0.4.0, so I'm not suggesting discussing it further at present. But perhaps it should be reopened, as a reminder to revisit it.