(LaTex) Math formulas rendering support

[jancura]

For math projects, one wants to document the code by using math expressions. However, currently, docfx does not support rendering of math if I use latex style definitions of formulas in my markdown files. Would be possible to add such feature into docfx?

[surban]

In my opinion the best solution would be to include KaTeX as a plugin. It uses the same license as DocFX (MIT) and can be included into the resources of the generated website. Thus no external web resources would be required.

[jancura]

Thank for the suggestion. I do understand which direction it is pointing but do you have an example how could I set it up? I understand that I download KaTex and then in the resource section of docfx.json I would specify where the KaTex is located but is that enough? I guess the HTML code generation of docfx would still need to figure it out that it needs to apply KaTex for rendering Latex formulas. Should it be implemented as post-processor plugin?

[cben]

Depends on what syntax you choose for math. See https://github.com/cben/mathdown/wiki/math-in-markdown for what others do — unfortunately no consensus :-(

For most syntaxes, for example $...$ delimeters, post-processing is not quite enough. Math formulas may contain characters that are meaningful in markdown, for example:

Foo $a*b$ bar $c*d$ baz.

Here, if you do unmodified markdown processing first you get something like:

<p>Foo $a<i>b$ bar $c</i>d$ baz.</p>

which results in (1) "bar" being wrongly rendered in italics (2) the math getting broken :-( There are also cases with _ and others...

Pre-processing doesn't quite work either — ideally you don't want to touch $ inside inline or block literals.

=> So you have to integrate math as a new inline syntax into your markdown parser.

However, literal-based syntaxes can work with an unmodified parser! For "display" math blocks, one would just use fenced block with a special "language" name, e.g.:

```math
\sum_{k=0}^\infty k^{-1}
```

and you simply post-process <pre> elements with math language with KaTeX / MathJax. Inline math is trickier, and more fragmented, because markdown has no convention to indicate type of inline literals. For example GitLab (but afaik nobody else) chose Foo $`a*b`$ bar $`c*d`$ baz syntax (note how the backticks shield the * from the markdown parser!).

Interoperability pro: literal-based syntaxes degrade safely in markdown processors that don't understand the syntax. Interoperability con: few tools implement literal-based math. Interoperability con: people that know LaTeX are happiest if the LaTex syntaxes they already know Just Work.

[cben]

Syntax choice might be influenced by #2292, #2347 — if you're also looking to support Mermaid, PlantUML and other "foreign" syntaxes via literal blocks, makes sense to treat math similarly... Especially if it allows implemetation in a plugin (?)

(above is all generic advice; I'm not familiar with docfx...)

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[dkmiller]

Now that Azure DevOps supports LaTeX rendering, this would be a good way to provide parity.

[superyyrrzz]

@dkmiller Thank you for the info! Related doc: https://docs.microsoft.com/en-us/azure/devops/release-notes/2017/nov-28-vsts#wiki-supports-mathematical-formulas

Actually, this is supported on docs.microsoft.com. We can see some page using it. I will mark this feature as DocsParity for v3 to support.

[jimhanks]

I know this is an old thread but when I google "docfx math" it is still the first hit. I agree with @cben above who said "you have to integrate math as a new inline syntax into your markdown parser" but it doesn't look like that is forthcoming. I have the beginnings of a work around, but I'm wondering if anyone has come up with something better.

So far what I've discovered is that we need two pieces: the markdown rendering and the HTML rendering. The HTML rendering is pretty simple. Stealing an idea from here, I added some simple custom templating to my docfx project like this: conceptual.html.primary.tmpl.txt to hook into the MathJax library for doing the HTML rendering.

Then if I edit the HTML files to put in something like this: <span class="math">\(e^{i\pi} + 1 = 0\)</span>

I get math rendered to the browser window. Nice!

OK, so how can I generate that HTML from markdown? Of course, I'd like to be able to write something like this $e^{i\pi} + 1 = 0$. and have the markdown parser translate that into the span element, but we don't have that. What if I just put the HTML directly in the .md file? Well, that doesn't work because of the backslash escaping logic in the markdown parser, but if I write it like this: <span class="math">\\(e^{i\pi} + 1 = 0\\)</span> Hey that worked!

So I could potentially write my .md files with that syntax and maybe get by until (?) docfx provides an alternative, but....

• I'm sure there will be trouble with asterisks, underscores, etc. as alluded to above
• I'm sure there will be more trouble with backslash sequences
• it makes the .md files really ugly

I'm hesitant to go down the road of trying to write a pre-processor or post-processor for reasons stated above, but looks like there aren't many options without official docfx support.

Does anybody have any newer thoughts or ideas?

[jimhanks]

Oh wait. After playing with this some more, I'm finding that the <span class="math"> isn't critical at all. MathJax is reading the $$ syntax (for paragraphs) and \( syntax (for inline) directly as part of its magic. The fact that I have to use \\( is due to the markdown parser. But this means I can probably do what I want without a pre-processor or post-processor. I'm going to run with that idea and see what other roadblocks I run into.

[flecmart]

if you find a good solution I would be interested in how to integrate it :-)

[bradkarhu]

GitHub flavored markdown supports it now: https://github.blog/2022-05-19-math-support-in-markdown/

Today we are pleased to announce that math expressions can be rendered in Markdown on GitHub using $$ as a delimiter for code blocks with math content or the $ delimiter for inline math expressions.

They went with MathJax over KaTeX