Bug: nbconvert mathjax conflict with arithmatex

[eckelsjd]

Background:

Users of the pymdownx.arithmatex extension are used to the following mathjax configuration:

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

which is supported especially in the mkdocs-material docs for displaying Latex equations. The arithmatex extension by default will convert all "math-like" blocks in .md files to html wrapped in the "arithmatex" class, which is then found by Mathjax using the above configuration.

mkdocs-jupyter however, uses nbconvert to generate html, which does not wrap "math-like" blocks, such as $ $ or \( \), in this "arithmatex" class (which is fine because it's a different extension altogether).

The problem is, users of arithmatex (and mkdocs-material in general) would expect mkdocs-jupyter to display math normally out of the box, but since it goes through nbconvert, the Mathjax configuration above no longer works. Instead, it prevents Mathjax from finding math blocks produced by nbconvert (due to the ignoreHtmlClass line I believe).

Desired behavior:

• You should be able to configure mkdocs-jupyter to produce Math text in an arithmatex/mkdocs-material-supportive way, so that...
• math text produced by mkdocs-jupyter (and therefore by nbconvert) should work using the (very common) Mathjax config above.

Current behavior:

• Math text produced by nbconvert will be hidden from Mathjax using the config above, and so Math like $ $ does not get properly displayed using the mkdocs-jupyter plugin.

Workaround

• A very simple workaround seems to be just removing the ignoreHtmlClass line from the Mathjax config. That way the Math text produced by nbconvert can still be found by Mathjax.

A better solution

• After some serious bikeshedding, I believe a much better solution would be for mkdocs-jupyter to support passing more configurations through to nbconvert, especially the ability to override the nbconvert jinja template, which right now is hard-coded here in mkdocs-jupyter. See this related issue that also would benefit from this feature.

Also, for posterity, see this related discussion where the custom_mathjax_url option was added to mkdocs-jupyter to allow better configuration of nbconvert.

If I could specify my own template_file such as

plugins:
  mkdocs-jupyter:
    extra_nbconvert_opts:
      template_file: /path/to/my/template
      mathjax_url: (already an option on its own)
      other_opts: (e.g. that might benefit other people)

Then on this HTMLExporter, you would just pass **extra_nbconvert_opts. For anyone still interested, I can already see that for my specific use case, I would specify a template like this:

{% block markdowncell scoped %}
<div {{ cell_id_anchor(cell) }} class="jp-Cell jp-MarkdownCell jp-Notebook-cell">
<div class="jp-Cell-inputWrapper">
<div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
</div>
<div class="jp-InputArea jp-Cell-inputArea">
{%- if resources.global_content_filter.include_input_prompt-%}
    {{ self.empty_in_prompt() }}
{%- endif -%}
<div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput {{ celltags(cell) }}" data-mime-type="text/markdown">
{%- if resources.should_sanitize_html %}
{%- set html_value=cell.source  | markdown2html | strip_files_prefix | clean_html -%}
{%- else %}
{%- set html_value=cell.source  | markdown2html | strip_files_prefix -%}
{%- endif %}
{{ html_value.replace('<p>', '<p class="arithmatex">') | safe }}
</div>
</div>
</div>
</div>
{%- endblock markdowncell %}

which would override the nbconvert template for jupyter markdown cells -- allowing me to pass in the "arithmatex" class so that Mathjax can find it using the config above. Phew. Isn't that much easier than the one-liner workaround... 🫠