Document the rendering workflow with dollarmath

[ubitux]

Context

The original js dollarmath plugin is documented on how to use it, but we can't apply that information to Python because the workflow is pretty different (there is a bridge to build between the Python output and the JS).

Proposal

At first I tried to use the renderer parameter, where we supposedely have to craft javascript code for each snippet and render it in-place. Doing that would require inserting a <script> able to identify the position in the DOM, which as far as I can tell might not be doable. Pushing the idea further, we could imagine inserting both a unique <div> marker and the <script> and then rework the DOM when the tag is relocated later on.

That seemed a bit too convoluted so I took a different approach by not setting any renderer and simply added that at the top of my HTML:

        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-wcIxkf4k558AjM3Yz3BBFQUbk/zgIYC2R0QpeeYb+TwlBVMrlgLqwRjRtGZiK7ww" crossorigin="anonymous">
        <script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-hIoBPJpTUs74ddyc4bFZSM1TVlQDA60VBbJS0oA934VSz82sBx1X7kSx2ATBDIyd" crossorigin="anonymous"></script>

        <script>
        document.addEventListener("DOMContentLoaded", (event) => {
          const math_elems = document.getElementsByClassName("math");
          for (let i = 0; i < math_elems.length; i++) {
            const element = math_elems[i];
            const display_mode = element.classList.contains("inline") ? false : true;
            element.innerHTML = katex.renderToString(math_elems[i].innerText, {displayMode: display_mode});
          }
        });
        </script>

This is still not perfect because we loose the display mode information (so the inline double display mode is wrong) but it does seem to work otherwise. Addressing that last issue would probably require using the renderer mechanism to inject some information stripped into that loop but it's unclear to me exactly how.

Is there actually a way of working this out I'm missing here?

Tasks and updates

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉