Adding a javascript script tag some place so that it works for every file in sphinx documentation

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.


Another method:

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


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.

Tags:

Python

Javascript

Python Sphinx

Recent Posts