Idea: top-level environment option

KaTeX currently essentially only supports $...$ and $$...$$ for entering math mode. It doesn’t support:

• \begin{equation}...\end{equation} (#445, which includes automatic equation numbering #350)
• \begin{eqnarray}...\end{eqnarray} (requested once in #1931)
• \begin{align}...\end{align} (similar effect to $$\begin{aligned}...\end{aligned}$$, as described in one of our common issues, but the effect is actually very different with equation numbering, so this will be more relevant with #350, and it’s even an issue with \tag, see also #2004)
• \begin{alignat}{n}...\end{alignat} (but, having an argument, this one isn’t addressed by this proposal)
• \begin{gather}...\end{gather}
• \begin{multline}...\end{multline}
• \begin{flalign}...\end{flalign} (#1990, though we have the related option fleqn)

I propose a new render option with a name like mathEnv or topEnv or env or something, or else a redefinition of displayMode to allow values other than false (meaning $...$) and true (meaning $$...$$). Either way, I’d like to allow values like equation, eqnarray, eqnarray*, align, align*, split, split*, gather, gather*, flalign, flalign*, multline, multline*, as well as math (equivalent of inline $...$) and displaymath or equation* (equivalent of display $$...$$). Then we could add a matching option to auto-render’s delimiters (or replacing the existing display option) so that \begin\s*{equation}...\end\s*{equation} would end up calling render with the top-level environment set to equation.

This would finally let us support other top-level math environments in what I believe is a natural way. Assuming you like the idea, I’d appreciate some suggestions on the name for the option, or whether to overload displayMode, or whether to deprecate displayMode (as it’s effectively redundant with this option).

[ylemkimon]

Related: #604.

[edemaine]

@kevinbarabash That’s a neat idea (though a little ugly). But beyond how to notate entering KaTeX in text mode (that’s an auto-render issue), there’s no way to enter the main KaTeX engine starting in text mode. I guess we could add an option to render/renderToString which specifies an initial mode of text or math (defaulting to math)… but I fear that this would be much harder to implement, because parsing LaTeX in text mode is a much taller order than our current support of \text, because that only required supporting TeX horizontal mode. Whereas \begin{align} ... \end{align} only makes sense in TeX vertical mode, which we are really far away from supporting.

So I think it’s best to stick to fixing “how do I specify the top-level math environment”. I guess life would be easier if the argument to render/renderToString already included the wrapping $s or \(...\) or \[...\] – then the user could just specify a different wrapping environment. So another way would be to add an option like wrapped that specifies whether the argument has the wrapper. But the outer wrapping environment really does behave differently from everything else that we support. Hmm, now I see that this might be exactly what @kevinbarabash meant by “limited top-level text mode”.