Katex: auto-render options not documented

[edemaine]

I was surprised to not see documentation of the special options supported by renderMathInElement, in particular delimiters which we often get questions about, in the auto-render extension documentation page. Before I forget, we should add that, ideally along with a common alternative for delimiters (and warnings about order).

[jason-s]

Huh, that's timely, I just ran into the same issue. Would someone mind posting an example here? Because I want to configure the delimiters and I don't know how.

oh, never mind, UTSL revealed the magic:

https://github.com/KaTeX/KaTeX/blob/master/contrib/auto-render/auto-render.js#L96

 optionsCopy.delimiters = optionsCopy.delimiters || [
        {left: "$$", right: "$$", display: true},
        {left: "\\(", right: "\\)", display: false},
        // LaTeX uses $…$, but it ruins the display of normal `$` in text:
        // {left: "$", right: "$", display: false},

        //  \[…\] must come last in this array. Otherwise, renderMathInElement
        //  will search for \[ before it searches for $$ or  \(
        // That makes it susceptible to finding a \\[0.3em] row delimiter and
        // treating it as if it were the start of a KaTeX math zone.
        {left: "\\[", right: "\\]", display: true},
    ];

[jason-s]

...so a complete workable example seems to be:

<script type="text/javascript">
  document.addEventListener("DOMContentLoaded", function() {
    renderMathInElement(document.body, {
      delimiters: [
        {left: "$$", right: "$$", display: true},
        {left: "\\(", right: "\\)", display: false},
      ]
    });
  });
</script>

[kevinbarabash]

@jason-s would be interested in updating the example in https://github.com/KaTeX/KaTeX/blob/master/docs/autorender.md?

[kevinbarabash]

@edemaine https://github.com/KaTeX/KaTeX/blob/master/docs/autorender.md does mention delimiters but agree that it needs a warning about the order. Are there options that are missing from that page?

[edemaine]

@kevinbarabash Ah, indeed it does, but that's not getting output to https://katex.org/docs/autorender.html . Docusaurus bug?

[kevinbarabash]

Thanks for pointing that out. Sounds like it could be a Docusaurus bug.

[kevinbarabash]

It turns out it's not a Docusaurus bug. There's an unclosed HTML comment in that .md file which is causing the issue.

[ronkok]

This issue is resolved by PR #1979. After the next KaTeX update, the documentation at https://katex.org/docs/autorender.html will be complete. Until then, the complete version is visible at https://katex.org/docs/next/autorender.html.