19

I am using Sphinx to write some notes. I am using the Mathjax extension for Math in the notes. The default size of the math is little larger than I would like. On the Mathjax page I found that I can change that size by adding the following script to the HTML file.

MathJax.Hub.Config({ "HTML-CSS": {scale: 90} });

So, I tried by adding the following in a .rst file:

.. raw:: html <script type="text/javascript" > MathJax.Hub.Config({ "HTML-CSS": { scale: 90 } }); </script> ========== Objective ========== To change math size \\( \\alpha \\).

The above works great for the math in that specific .rst file. But I want to do this for many different .rst files that are all part of the same Sphinx document. Is it possible to do this without adding the above script to every .rst file?

Improve this question

5 Answers 5

Reset to default
25

This can be done with a template:

  1. Create a folder called templates in the Sphinx project directory.

  2. In conf.py, add

    templates_path = ["templates"]

  3. In the templates directory, create a file called layout.html with the following contents:

     {% extends "!layout.html" %} {%- block extrahead %} <script type="text/javascript"> MathJax.Hub.Config({ "HTML-CSS": { scale: 90 } }); </script> {% endblock %}

The <script> element will be included in the <head> of every generated HTML page.

The extrahead template block is empty by default. See the Sphinx templating documentation for details.

Improve this answer
Sign up to request clarification or add additional context in comments.

5 Comments

Thanks so much. This worked great! Thanks especially for the detailed steps. Why is there a - in the line {%- block extrahead}. Without the dash, it does not work. The code examples I have seen in the link do not have this -.
The default extrahead block in sphinx/themes/basic/layout.html has the extra hyphen/dash/minus (it is about whitespace control). But I can't really explain why it does not work for you without it...
Thanks. I will look into that. Anyhow, it works great with the dash. Thanks again for responding.
I did not need the dash. This worked great for adding the Tex extension mhchecm.js to so I could use \ce tex tags to create chemical equations using mhchem.
The latest MathJax docs say to use "text/x-mathjax-config" as the script type instead of "text/javascript" EG <script type="text/x-mathjax-config">
5

If you want to avoid altering templates, you can just call Sphinx's add_js_file() from the setup() function in your Sphinx project's conf.py:

# conf.py # ... other settings ... def setup(app): # (create a setup() function if you don't already have one; # or add to the existing setup() ...) app.add_js_file("mathjax-config.js")

Create the file "mathjax-config.js" in your _static source directory. (Check the conf.py html_static_path setting to verify the static directories, or define one if needed.) Sphinx will copy it into the output directory during the build.

There's also an add_css_file() method for CSS files. And both of them can take either relative paths to your static source dirs, or full URLs to external resources.

Before Sphinx v1.8, these functions were called add_javascript() and add_stylesheet().

And in Sphinx v3.0 or later, there's an even simpler approach that avoids the need for an extra JS file.

Improve this answer

2 Comments

It seems this requires setting up an extension, is that correct?
No extension required: you can place a setup() function in your project's own conf.py. (Your project is effectively allowed to be its own extension.)
3

Another method:

Use the script_files setting in your overridden layout.html file.

Improve this answer

Comments

2

In Sphinx 3.0 and later, the easiest way to add short snippets of JavaScript configuration is to call app.add_js_file(None, body="...JS code...") in your conf.py setup function. Example:

# In your Sphinx project's conf.py: # 1. Add whatever JS code you need as a string constant. # (This example is from the original question.) MATHJAX_CONFIG_JS = """ MathJax.Hub.Config({ "HTML-CSS": {scale: 90} }); """ # 2. Create a setup() function if you don't already have one. # (If you do, just add to your existing setup() function.) def setup(app): # 3. Tell Sphinx to add your JS code. Sphinx will insert # the `body` into the html inside a <script> tag: app.add_js_file(None, body=MATHJAX_CONFIG_JS)

With this approach, you don't need to create a separate, static JS file.

(The body param was added in Sphinx 3.0; with earlier versions you can still use add_js_file() with a static JS file—see my earlier answer. And for for anything longer than a short config snippet, it's probably better to use an external file anyway.)

Improve this answer

2 Comments

It's me again :) I think that in this case a type="text/x-mathjax-config" is mandatory, as MathJax's initiation will run those scripts (cf. docs.mathjax.org/en/v2.7-latest/… ). Also here, thanks for considering an edit!
In larger projects the previous answer is advisable to avoid cluttering the conf.py although it requires the extra step of setting up html_static_path.
1

The simplest solution for a conf.py only configuration might be to use the MathJax extension's config value mathjax_config (Available since 1.8). The value of mathjax_config is passed to MathJax.Hub.Config().

In your specific case, add the following to conf.py:

mathjax_config = { "HTML-CSS": {"scale": 90}, }
Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.