Render mathematical expressions in Markdown

Many tools like vscode support rendering math expressions in LaTeX style inside Markdown. Since a few weeks this is also supported here on GitHub.

I.e. we can put our expression into two $ $$y = xA^T + b$$ and get a nicely rendered expression: $$y = xA^T + b$$ Or alternatively we can get inline rendering $y = xA^T + b$ by using a single $: $y = xA^T + b$

Rendering is done with MathJax, an apache-licenced JavaScript rendering library that can be included in any webpage.

I think this is quite useful for documentation inside of i.e. numeric and scientific libraries or just anything with math operations so I’d like to propose to add support for MathJax in Scaladoc.

I did a small POC by including the necessary JS and config manually into a Scaladoc generated html file, and it seems to work well:

<script>
    MathJax = {
        tex: {
            inlineMath: [['$', '$']]
        }
    };
</script>
<script type="text/javascript" id="MathJax-script" defer="true" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

I guess the MathJax script URL using a CDN should be added here: https://github.com/lampepfl/dotty/blob/6635929a036ac8d340cd17eaea0c2a89bbc497b2/scaladoc/src/dotty/tools/scaladoc/renderers/Resources.scala#L111-L117

I’m less sure about configuration script. Should that be generated from Scala? If someone more familiar with the codebase could point me in the right direction I’d be grateful.

[julienrf]

Do you think scaladoc should or could be extensible so that third parties could provide support for various features (e.g., mermaid diagrams, etc.)?

[pikinier20]

So, basically I think that the simplest way to add this config would be to generate a small file with script. You can see an example in file Resources.scala :

private def dynamicJsData =
    val str = jsonObject("filterDefaults" -> jsonObject(
      FilterAttributes.defaultValues.toSeq.map { case  (n, v) => n -> jsonString(v) }:_*
    ))
    Resource.Text("scripts/data.js", s"var scaladocData = $str")

So, you need to generate the Resource.Text object and then append it to commonResources. First param describe the path in which the file will be rendered, second param is the body of file.