Skip to content

Made loading mathjax, plotly and mermaid optional for each page #3237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

Gabri110
Copy link
Contributor

@Gabri110 Gabri110 commented Aug 5, 2025

Performance of the theme could be greatly enhanced if support for MathJax, Plotly and Mermaid was enabled only when necessary. A simple way to do this would be to do in _includes\footer\custom.html
{% if page.mathjax %} <script defer src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es6"></script> <script defer src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js" id="MathJax-script"></script> {% endif %}
and set mathjax: true in the defaults of _config.yml.

If a certain page does not require mathjax then the user could set mathjax: false in the YAML header of the page, thus saving a lot of JS runtime! All of this is also applicable for plotly and mermaid.

Personally, I'm setting by default mathjax: false. But this may complicate using the theme for new users.

@rjzupkoii
Copy link
Collaborator

This is something that I've thought about for #3151, but I'm still on the fence for if it should be done or not since if it's a site-wide setting like this PR then you still end up with the performance issues on each page where the libraries are not needed. I have tried experimenting a bit with delayed loading of the libraries which helps the time-to-render but in a lot of cases that introduces new issues. Another approach would be to have a custom script that scans the Markdown to see if the files are needed and then add the includes, but that would need to be done as a build step which is non-trivial.

@Gabri110
Copy link
Contributor Author

Gabri110 commented Aug 7, 2025

@rjzupkoii I have made that you could set loading mathjax as an individual option for each page separately through an option in the YAML header. Or at least that's how it works in theory.

@rjzupkoii
Copy link
Collaborator

@Gabri110 Toggling it in the header of each page is actually how al-folio does, but their userbase does sometimes common on that template being much more involved for the user. The design philosophy for Academic Pages is to keep things as simple as possible for the user so the less settings that they need to adjust the better.

@Gabri110
Copy link
Contributor Author

Gabri110 commented Aug 7, 2025

Right, I see. Perhaps toggling the three settings (mathjax, mermaid, plotly) could be combined into a single one, called 'performance-mode', or something similar? Anyways, following the method that you suggested earlier would be fantastic, but it requires a bit of effort haha

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants