MathJax 利用ノート

本稿は MathJax の利用について得た知見を記す。まず何の準備もなしに MathJax を利用する手順を述べる。さらに自分で編集する HTML ファイルから MathJax の機能を、生の HTML ファイルと Sphinx が生成する HTML ファイルそれぞれから利用する手順を、マクロを定義する方法を、それも保守が容易な方法を含めて説明する。

Note

本稿執筆時の動作環境は次のとおり。

関連リンクおよび参考サイト

MathJax

MathJax の開発陣による文書一揃い。まず Basic Usage を一通り読み、それから気になる論題をつまみ食いするとよい。

LaTeX

LaTeX を一通り習うための教科書として参照する。

MathJax を試す

ダウンロードやインストールなどの作業をすることなく MathJax を簡単に試すことができる。

Dynamic Preview of Textarea with MathJax Content をウェブブラウザーで開き、何か簡単な TeX コードを指示通りにテキストエリアにタイプすると、画面下部の枠内にレンダリング結果が表れる。

このページは LaTeX 環境がないところで急に単発の数式画像が欲しくなったときに、必要な TeX コードを打ち込んで容易にそれを得るという用途にも向いているだろう。

このプレビュー生成テストページを含む、現行バージョンにおける機能テスト用 HTML ファイル群がリポジトリーの以下のディレクトリーに豊富にある： <https://github.com/mathjax/MathJax/tree/master/test>

直接 HTML を作成する場合の方法

本稿の本題である自作の HTML ファイルで数式画像混じりの文書を作成するための、最低限の方法について記す。まず、上記プレビューページの HTML コードの本質部分を抽出して編集対象の HTML に組み込む。

MathJax を自作 HTML ファイルから機能させるための手順を列挙するとこのようになる：

  • HTML 文書の head 部で script タグをおそらく二箇所仕込む。

  • HTML 文書の body 部に所望の TeX コードを埋め込む。

スクリプトタグをヘッダーに仕込む

正式な方法は MathJax の文書にあるが、本稿では最も単純な指定方式を採用する。差し当たり、HTML の head 部に次のような script タグを仕込めば準備は整う。

<script type="text/javascript" async
    src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

いくつかポイントがあるようだ：

  • MathJax.js の在り処は上記のもの以外にも存在する。文書では cdnjs.com を推奨している。

  • MathJax.js の config 引数は利用したい機能によって指定が決まる。上記のものは TeX-MML-AM_CHTML という、最も普通の構成を指定している。

処理対象マークアップを指示する

MathJax のロード指定と併せて、本文中のどの数式を MathJax に処理させるかを指定することができる。

次のような構成指定を実行するコードからなる script タグを、先ほど述べた MathJax.js をロードする script タグの直前に配置する。

<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    tex2jax: {
      inlineMath: [['$','$']],
      displayMath: [['$$','$$']],
    }
  });
</script>

こうすることで、次の効果が得られる：

  • 本文中、すなわち HTML 文書の body 要素中にあるドルマークで囲まれたテキストがTeX コードとして認識され、MathJax によりレンダリング処理が施されて画面上に出力される。

  • ドルマーク一個のペア、および二個のペアで囲まれたテキストは、 HTML の観点からはインライン要素およびブロック要素としてそれぞれ処理される。

この方法は単純でわかりやすいのだが、数式を書く HTML ファイルを複数作成するのであれば別の手段を採用するのが妥当だ。設定・構成コードは可能な限り専用の外部ファイルに記述して、関連する複数の HTML ファイルから参照されるようにしたい。このような方法については後ほど Sphinx の節で述べる。

数式を本文中に挿入する

あとは HTML 文書の body 要素における数式を $..$ なり $$...$$ なりで囲めばよい。

Sphinx で生成する場合の方法

以上を踏まえて、Sphinx で MathJax の機能を利用可能にする手順を述べる。

既存の Sphinx プロジェクトが MathJax 機能を無視して構築されている場合の手順としては次のようになる：

  • Sphinx の構成ファイルを編集する

  • MathJax の構成ファイルを作成する

  • HTML テンプレートを編集する

ゼロから Sphinx プロジェクトを開始する場合には sphinx-quickstart の対話的処理で MathJax の拡張機能を有効とするように指示すればよい。

Please indicate if you want to use one of the following Sphinx extensions:
...
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
...

以下、各項目を説明する。

Sphinx の構成ファイルを編集する

既存の Sphinx プロジェクトが MathJax 機能を無視して構築されている場合、この手順を必要とする。

Sphinx プロジェクト用の構成ファイル conf.py をテキストエディターで編集する。次のように変更する：

  • リスト extensions に 'sphinx.ext.mathjax' を追加する

    • ゼロから Sphinx プロジェクトを開始する場合には sphinx-quickstart の対話的処理で MathJax の拡張機能を有効とするように指示してあれば、リストにこの値があるはずだ。

MathJax の構成ファイルを作成する

とりあえず最低の動作確認しかしたくないのであれば、ここは飛ばして構わない。

後ほど MathJax の機能を調整することを見込んで、 Sphinx プロジェクトディレクトリー _static に次の内容のテキストファイルを作成する。

window.MathJax = {

    // ... 先ほどの MathJax.Hub.Config 呼び出しの実引数と同じ内容を書く。
    // ただし tex2jax オブジェクトの inlineMath と displayMath を普通は外す。

};

以下、このファイル名を mathjaxconf.js としたものとして説明をする。

HTML テンプレートを編集する

とりあえず最低の動作確認しかしたくないのであれば、ここは飛ばして構わない。

  • Sphinx プロジェクト用の HTML テンプレート layout.html について、

    • このテンプレートファイルが Sphinx プロジェクトディレクトリーにない場合、 Sphinx プロジェクトのテンプレートディレクトリ―（既定では _template という名前である）に空の内容の layout.html を作成し、以下の内容で保存すればよい。

      {% extends "!layout.html" %}
{% set script_files = ["_static/mathjaxconf.js"] + script_files %}

    • 自前で Sphinx のテーマをカスタマイズしているのであれば、そちらの layout.html で script_files の値を適宜設定する。例えばその他のスクリプトがある場合などは、上述のリスト内リストが "_static/mathjaxconf.js" 以外にもパス文字列があるはずだ。

  • 書式は Jinja2 に従う。

マクロを定義する

公式文書にあるように、TeX マクロを定義することができる。やり方は MathJax.Hub.Config 呼び出しの実引数または window.MathJax に設定する JavaScript オブジェクトに次のようなオブジェクトを挿入する：

TeX:
{
    Macros: {
        NN: "{\\mathbb N}",
        ZZ: "{\\mathbb Z}",
        QQ: "{\\mathbb Q}",
        RR: "{\\mathbb R}",
        CC: "{\\mathbb C}",
        dd: ["\\mathrm d^{#1}", 1, ""],
        diff: ["\\frac{\\dd {#1}}{\\dd {#2}}", 2],
        // ...
    }
}

  • TeX と先述の tex2jax が並列されることになるだろう。

  • 連想配列 Macros のキーと値はそれぞれコマンド名とマクロ定義を意味する。

    • 引数がないマクロについては、値の型は文字列でよい。

    • 引数を指定するマクロについては、値をリストで指定する。リストの内容は順にマクロ定義を表す文字列、引数の個数、もしあればデフォルト引数……だ。

  • バックスラッシュはエスケープする必要がある。

  • マクロ定義は LaTeX ディレクトリーの /texmf-dist/tex/latex/akktex/*.sty が大いに参考になる。いくつかコツがある。

    • まず sty コードのバックスラッシュをバックスラッシュでエスケープする必要がある。

    • \\newcommand を定義するブロックを囲むための中括弧は削除する。

  • もし開発環境に LaTeX がインストールされていなければ、インターネットから検索しても十分間に合う。