Add support for MathJax equation numbering

[qbrak]

Using the flag 'number_equations:true' you can add equation numbering to MathJax. The numbering happens when you write equations using \begin{equation}...\end{equation} as described here:

https://docs.mathjax.org/en/latest/input/tex/eqnumbers.html

An example was included in:
_posts/2019-08-08-text-and-typography.md

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Improvement (refactoring and improving code)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Description

Option 1 (implemented)

I added a new flag:
'number_equations:true' in order to support equation numbering.

This flag changes the configuration for MathJax such that when true, MathJax supports equation numbering.

The change happens in js-selector.html and looks like:

  <!-- MathJax -->
  <script>
    /* see: <https://docs.mathjax.org/en/latest/options/input/tex.html#tex-options> */
    MathJax = {
      tex: {
        /* start/end delimiter pairs for in-line math */
        inlineMath: [
          ['$', '$'],
          ['\\(', '\\)']
        ],
        /* start/end delimiter pairs for display math */
        displayMath: [
          ['$$', '$$'],
          ['\\[', '\\]']
        ],
        {% if page.number_equations %}
          /* equation numbering */
          tags: 'ams'
        {% else %}
          /* by default don't number equations */
          tags: 'none'
        {% endif %}
      }
    };
  </script>

The tags: 'ams' causes MathJax to generate equation numbering inside \begin{equation} and \end{equation} blocks.

Option 2 (not implemented/simpler)

Potentially a simpler idea would be to have the equation numbering always on. This way, if someone wants to use it they can, but most people probably would not notice. I could prepare that patch if this is a direction you would be willing to pursue.

If the equation numbering would always be on, then:

$$ equation $$

Would work like previously.

However,

$$
\begin{equation}
equation
\end{equation}
$$

Would now require a \notag or \nonumber to skip the (1) that would appear on the right.

Additional context

This feature would be an answer to a previous request in issue #147

You can see a live demo of this working on https://qbrak.github.io/posts/how-to-least-squares

Here is the documentation from MathJax on how this works: https://docs.mathjax.org/en/latest/input/tex/eqnumbers.html

EDIT: I added more structure and clarity to the text

[cotes2020]

Looks good, it might be better to have number_equations as a parameter to math:

math:
  number_equations: true

For documentation we also need to add the tutorial in "Writing a New Post".

Also, it would be nice if you could follow the Conventional Commits style when submitting commits, so the CI doesn't report errors.

[qbrak]

@cotes2020 Thanks for the feedback.

I have been thinking about the differences between Options 1 and 2 (from the description). What I have implemented is Option 1 which is non-breaking, but it does introduce more complexity to the codebase (when you want equation numbering you need to set a new flag).

I was wondering if it would not be cleaner to just always enable equation numbering. So then we would have:

  <!-- MathJax -->
  <script>
    /* see: <https://docs.mathjax.org/en/latest/options/input/tex.html#tex-options> */
    MathJax = {
      tex: {
        /* start/end delimiter pairs for in-line math */
        inlineMath: [
          ['$', '$'],
          ['\\(', '\\)']
        ],
        /* start/end delimiter pairs for display math */
        displayMath: [
          ['$$', '$$'],
          ['\\[', '\\]']
        ],
        /* equation numbering */
        tags: 'ams'
      }
    };
  </script>

I have not found any issues online with this. The only case something would break was if someone used the following syntax:

$$ 
\begin{equation}
equation
\end{equation}
$$

instead of the simpler

$$
equation
$$

and the breaking behavior would be that they get an equation number on the right-hand side which they did not have previously.

Please let me know what you think. If you would still like to go with the 100% non-breaking option 1 I will implement your requested changes and update the PR.

[cotes2020]

After reading the documentation you provided, I vote for Option 2 because it meets the KISS principle.

MathJax = {
  tex: {
    tags: 'ams'
  }
};