Matrix not rendered properly in the docs about nx

[josevalim]

You can run MIX_ENV=docs mix docs (or just mix docs?) in the nx subfolder and you should be able to see results locally. :)

[jonatanklosko]

This is the same as elixir-lang/ex_doc#1571.

In this specific example this manifests in two ways:

• _ pairs being expanded to markdown italic
• \\ is escaped backslash and gets converted to \

[josevalim]

@ndrean, would you be able to take a look? Thank you!

[ndrean]

oh, indeed! I didn't looked at the Hexdocs. Time to dive into Hexdocs, Earmark and probably Mathjax.

[josevalim]

You can also find the configuration on nx/mix.exs.

[ndrean]

@jonatanklosko Maybe a naive quick thought: Earmark produces an HTML string, doesn't it? If we just ask Earmark to leave whatever is between $ signs, and embed MathJax in the rendered document (like adding a <script src=cdn mathjax...>), couldn't it render math? I also saw a MathJax.typeset

[jonatanklosko]

@ndrean we don't want Earmark to inject the script, that should be up to the user. But yeah, the proper solution is to make Earmark aware of $ and $$, so their contents are not interpreted as Markdown :)

[ndrean]

@jonatanklosko ah, I see you already inject Katex, somehow used the "mix": defp before_closing_body_tag(:html)

I don't understand/know the interactions between ex_docs, earmark, so I believe you have a better position to open an issue to earmark, if this is the potential response?

[josevalim]

We don't have another option to handle this that doesn't require changing Earmark? Make we can indent with four spaces and remove the wrapping pre tag accordingly?

[jonatanklosko]

@josevalim we could support alternative syntax (like GitLab, elixir-lang/ex_doc#1571 (comment)), but that creates more friction for people to use it. IIRC we were leaning towards $ and $$ support in Earmark, because GitHub added support for it.

[josevalim]

So request on Earmark it is. We will most likely have to contribute it. What do we do with this guide meanwhile? Can we avoid using _ or \\? Or should we keep it on GitHub and remove it from the docs?

[polvalente]

So request on Earmark it is. We will most likely have to contribute it. What do we do with this guide meanwhile? Can we avoid using _ or \\? Or should we keep it on GitHub and remove it from the docs?

\\ is used for linebreaks, so I think it's rather unavoidable. _ could maybe be substituted by ^ if we changed subscripts to superscripts

[ndrean]

When you look at the Nx guide - for example, https://hexdocs.pm/nx/intro-to-nx.html#broadcasts- you see that Latex is parsed correctly with $$ and \begin. The problem starts when you have nested commands (\begin{matrix} \begin{matrix}...)., so it might not be straightforward.

I would remove this one from the hexdocs for the moment, just keep the Livebook and a link to the Github.

[josevalim]

Done for now. The core issue is currently trackled on ExDoc. Thanks!