Adding mathjax—or any client-side library

[amingilani]

Hi, and first of all, thank you so much for creating this—it was perfect and got me up and running quickly!

I apologize, but I'm new to both Doks and Hugo all at once. That said, what would be the quickest way of installing MathJax in my docs?

Things I've tried:

• Just pasting in <script type="text/javascript" id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script> will fail in production
• Using SRI will also fail with <script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js" integrity="sha384-fNl9rj/eK1wEYfKc26CbPM6qkVQ+9MvYaoAFNql4ulbjBEWV2XLNP1UB8jQTtSe3" crossorigin="anonymous"></script>

I'm assuming this would apply to any client-side library like D3.js or Chart.js.

[h-enk]

Hi @amingilani, good to hear that you like Doks!

There are a number of ways to do this . A quick way would be:

1. Add to ./layouts/partials/head/script-header.html (see also Getting Started):

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

2. Update the Content-Security-Policy section in ./layouts/index.headers (see also Security Headers):

  Content-Security-Policy: default-src 'self'; manifest-src 'self'; connect-src 'self'; font-src 'self' https://cdn.jsdelivr.net/; img-src 'self' data:; script-src 'self' https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js https://polyfill.io/v3/polyfill.min.js; style-src 'self' 'unsafe-inline'

Then, when you add e.g. the following to a markdown content file:

<p>
When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are \[x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\]
</p>

This will be converted as follows:

P.S. (1) Note the added <p></p> tags in the markdown (unfortunately, Hugo does not support goldmark-mathjax — yet)

P.S. (2) I'm planning to write a guide on adding KaTeX — will be available soon. And, a more general guide like you hinted. Both guides will use npm for adding the scripts (for better dependency management and improved security reasons mainly).

Hope this helps!

[amingilani]

Thank you for this @h-enk for that wonderfully detailed answer! You've honestly put an incredibly amount of work into this project, and it shows. Thank you.

The trouble here is that the Content-Security-Policy doesn't cover the additional imports MathJax's js file makes. I could add them all manually, and I can even pin the version number and use a Subresource Integrity hash when importing it, but then I run into errors for my inline configuration.

Is there any way to use NPM to install import MathJax and bundle it in the JavaScripts?

[h-enk]

The general approach is:

1. npm install [<@scope>/]<name>
2. add to ./config/_default/config.toml:

   [module]
     [[module.mounts]]
       source = "node_modules/[<@scope>/]<name>[/dist]"
       target = "assets/js/vendor/[<@scope>/]<name>"

3. add to ./layouts/partials/footer/script-footer.html:

   {{ $<name>:= resources.Get "js/vendor/[<@scope>/]<name>/<name>.min.js" -}}

4. add $<name> to the slice lines (2x) in ./layouts/partials/footer/script-footer.html:
5. add configuration (if applicable) to ./assets/js/app.js

[h-enk]

The trouble here is that the Content-Security-Policy doesn't cover the additional imports MathJax's js file makes. I could add them all manually, and I can even pin the version number and use a Subresource Integrity hash when importing it, but then I run into errors for my inline configuration.

BTW, my "quick way" does work/is doable (forgot to send you earlier):

See:

• repo: https://github.com/h-enk/doks-79
• site: https://priceless-wing-4b06fe.netlify.app/docs/prologue/introduction/
• Mozilla Observatory: https://observatory.mozilla.org/analyze/priceless-wing-4b06fe.netlify.app

That is without configuration I know, but when you put your config in ./assets/js/app.js I think it should also work (not tested though).

[amingilani]

Thank you so much @h-enk! I'll try this out and get back to you soon 🙂