Mkdocs-material: Can't inject MathJax Config

[facelessuser]

Description

Impossible to configure MathJax in release candidate. While it is nice that Material loads MathJax for you when arithmatex is used, it is currently impossible to specify your MathJax config before it gets loaded. If there is no easy way to specifically overload the MathJax block, or inject a config before MathJax gets loaded, I imagine I would prefer it not to get loaded and I could just include my config and CDN link in extra JS in the proper order. People may want simple things like just adding reference numbers to their equations or aligning equations left which is impossible in the current setup.

Expected behavior

Some way to inject MathJax config.

Actual behavior

MathJax is loaded before extra_js, so there is no way to configure it before.

Steps to reproduce the bug

1. Cannot inject config before MathJax CDN is included.

Package versions

• Python: Any
• MkDocs: 0.16.1
• Material: 1.0.0rc2

System information

• OS: Any

[facelessuser]

Okay, it's not impossible. You can inject a config, but I basically have to do it in the markdown itself. I basically have to put this at either the top or bottom of the Markdown file that actually has equations:

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
    config: ["MMLorHTML.js"],
    extensions: ["tex2jax.js"],
    jax: ["input/TeX"],
    tex2jax: {
        inlineMath: [ ["\\(","\\)"] ],
        displayMath: [ ["\\[","\\]"] ]
    },
    TeX: {
        TagSide: "right",
        TagIndent: ".8em",
        MultLineWidth: "85%",
        equationNumbers: {
            autoNumber: "AMS",
        },
        unicode: {
            fonts: "STIXGeneral,'Arial Unicode MS'"
        }
    },
    displayAlign: 'left',
    showProcessingMessages: false,
    messageStyle: 'none'
});
</script>

It would be nice if the MathJax injection was in its own template file so I could override it (and only it) in my project, or if it was just left up to the user to configure so it could be global instead of injecting the config per file.

[squidfunk]

I did not think about configuration options, thanks for pointing it out. Therefore it's better to write in the documentation of how to integrate MathJax and leave it up to the user. I will fix that.

[facelessuser]

I know you mention you plan to document configuration. Do you plan on removing auto-adding of MathJax or do you plan on including MathJax after user extra JavaScript?

[squidfunk]

What's the better approach? I'm not a user of MathJax, so if you can outline the ideal way we can do it like that.

[facelessuser]

Honestly, I think just removing it and let people load it via extra_javascript, they can also load a custom config there if they need to as well.

Anyways, I wasn't sure what your plan was, I was just curious.

[squidfunk]

Sounds good. Can you provide an example of how to do it with extra JS, so I can add it to the docs?

[facelessuser]

Sure thing. I will try and get to it tomorrow. It's actually pretty late here.

[facelessuser]

@squidfunk, so here is what I did: https://github.com/facelessuser/pymdown-extensions/commit/484a8a1963e76baa96187e8f5a7cb8d8737ef6bd

1. You can see I override your base.html for now so I could remove your mathjax configuration.
2. In my extra.js, I specify my MathJax config tweaks.
3. I pick a default MathJax Configuration (in this case it was what you were already including config=TeX-MML-AM_CHTML).
4. I load my config extra.js first and then MathJax.js in mkdocs.yml.

That's it. It's really easy. Just include your config before MathJax load, and then inlcude MathJax. If you have any questions, feel free to ask.

[squidfunk]

Should be fixed in 82b8c7105929963a14ada29098c59688c9e91aba. I also updated the docs with the how-to you provided. Can you verify?

[squidfunk]

Closing this, will be released with 1.0.0.