Formula rendering

[ashwinvis]

Discuss mathjax and/or katex rendering here.

PRs

Mathjax: #7, #31, #41, #53 Katex: #46

Replaces issue: #40

[ashwinvis]

@twidxuga Do you think maybe we can use https://github.com/waylonflinn/markdown-it-katex, which seems to be more popular. Maybe then we won't need to ship the fonts. I didn't have to do it with markown-it-mathjax.

[twidxuga]

@ashwinvis, that is a good observation, though my fork uses makrdown-it-katex, and doesn't have a direct dependency of Katex in my package.json . I am using markdown-it-katex version 3.1.0 from this package, since it uses the latest Katex 0.10.1.

However, a closer look at my node_modules folder, reveals that there is in fact another copy of the Katex fonts within the katex node module folder, that is downloaded automatically on npm install.

In other words, there should be no need to ship any fonts for Katex - I just need to understand how to make the fonts installed automatically by npm available has static resources to the website without having a copy in the static resources folder (I added an explicit static resources folder in my fork for css, js, fonts, images, etc.), perhaps a symbolic link... I am pretty sure I would have the same issue if I was to used markdown-it-mathjax in my fork - this is far from ideal.

With regard to the Mathjax vs Katex rendering, Mathjax is used by Jupyter notebooks is memory serves, it is most likely fully fit for purpose, and I may be stirring the pond without necessity. Plus, it should be relatively easy to swap between the two.

What we could do is to try each others fork, and check for rendering speed, quality, completeness, etc.. I have a long document made with instant-mardown here that I will be using to check on my end.

Having both options available and configurable is possible, especially if we don't have to bundle fonts. But is it desirable?

In summary, I will try to have a look (this week or so) at:

• How to remove dependence on a copy of Katex fonts as a static resource

• How well Mathjax performs

  (edited due to typos)

[ashwinvis]

Good suggestion, I will checkout your fork in the weekend again. I am sure katex would be faster.

You should also try: https://gist.github.com/ashwinvis/617f885e68c88e887a06e02a78732ba8 which will help you realize that katex does not have all the features that mathjax provides.

[twidxuga]

So I just spent some time reviewing the code on both our forks of instant-markdown-d and to a lesser extent vim-instant-markdown. I also tested both forks in terms of rendering. The following are my observations:

1. While Katex rending is visibly faster, I did not find Mathjax's rendering speed to be a major issue, even with large documents, with rendering speed differences being barely noticeable, or not at all, especially if I am focussing on the Latex of the formula that I am typing.

2. Katex seems to implement a subset of Mathjax's latex formula rendering primitives, and as such I did not find anything written with Katex in mind to break when rendered with Mathjax, but the opposite is not true. If we were to start using Mathjax today no one's markdown documents would need to be changed in order to be rendered correctly.

3. Formula rendering with Mathjax has generally higher quality, font sizes are more consistent. Over time, I found Katex to be fiddly with regard to combinations of fonts+css that resulted in a more consistent rendering with instant-markdown-d.

   • mathjax render example
   • katex render example of the same markdown
   • markdown file used

From these points, plus the fact that Mathjax is more mature/established (used in Jupyter), my view is that using Mathjax is the way to go for formula rendering.

Looking at your code, it looks like you faced the same problem I did regarding the location of the Mathjax fonts and other assets to serve. Instead of serving the fonts resulting from installing the npm package (that are inside the node_modules/mathjax folder), you prefered pointing to the fonts from an external package using the environment variable INSTANT_MARKDOWN_MATHJAX_FONTS to get the path for those fonts. The problem I see with this is that the mathjax package that exists in your system may have a different version than that used by instant-dmarkdown-d (in my case mathjax appears to have been installed as a dependency of Jupyter). There might also be a security problem by which an attacker will manipulate that environment variable to gain access to other files in the system.

I suggest serving fonts, css, images, etc. from a static resources folder within instant-markdown-d. This will allow control over fonts are served (and those could be copied from node_modules/mathjax folder by an installer script, to avoid redundancy), as well as other assets exposed.

There are a series of other topics to discuss later, such as the best approach to serve files, passing parameters from vim-instant-markdown to instant-markdown-d (none are passed in Suan's fork, at least in Neovim), etc. but perhaps those belong in separate threads.

I like the improvements to CSS that you made, btw, better use of space and layout resizing.

(edited, of course there were typos)

[ashwinvis]

Thanks for checking. Yes mathjax is nice, but I am not 100% satisfied with the way things work. Since every time you type something the whole document is rendered again, nothing is cached. I have to use the "slow" rendering option to have something useful when I edit lengthy documents. Caching would be nice but it is beyond my skills.

The environment variable INSTANT_MARKDOWN_MATHJAX_FONTS is optional, and I believe if it is not provided it uses the mathjax CDN to download the fonts. I cannot be sure either since I have mathjax installed too.

Let me see if it is possible to use the mathjax from the node_modules directory.

[twidxuga]

Indeed, caching would be nice. Perhaps, splitting markdown documents in chunks, and only send those modified to the browser for partial document rendering on each edit... something for the long run, I guess.

I haven't yet experienced performance issues editing lengthy docs with Katex, even though the entire page is rendered. I usually use this document, though it can be argued that it is not long enough. That it is not to say that it could use caching as well. My workstation is relatively recent though and that may hide the problem.

I will do some more experimenting with Mathjax and long documents.

[twidxuga]

So I finally had time to do some more experimenting with Mathjax and Katex, this time including edits on large documents with formulas (machine learning papers, peppered with formulas).

As it turns out, and consistently with what you mentioned earlier, for larger documents Mathjax is painfully slow. The rendering is perfect but it is just not WYSIWYG. Katex has none of these problems. This makes Mathjax impractical for my own use.

On the positive side, I managed to get Katex to render just as well as Mathjax in my own fork, in the vast majority of cases, by fixing some bugs on the file serving side. I also prefer my own file serving policy (serving files from the root folder of the file being rendered).

To try my fork you need the instant-markdown'd server and the vim-instant-markdown pluging, as well as a couple of additional configuration options that are specified on the README.md.

https://github.com/twidxuga/instant-markdown-d

https://github.com/twidxuga/vim-instant-markdown

Example .vimrc/init.vim configuration:

" Disable autostart for instant markdown. :InstantMarkdownPreview
let g:instant_markdown_autostart = 0
" Opent the instant markdown port to the network
let g:instant_markdown_open_to_the_world = 0
" Allow serving all kind of content
let g:instant_markdown_allow_unsafe_content = 1
" Allow inclusing on external links
let g:instant_markdown_allow_external_content = 1
" Serve sub-fulders nested starting from the source markdown's folder (twid's)
let g:instant_markdown_serve_folder_tree = 1
" COMMENT Mathjax options for suans's branch
"let g:instant_markdown_slow = 1
"let g:instant_markdown_mathjax = 1

For now, due to work commitments, I will need to use this forked version, that also fixes a few other issues for me (on Linux with Neovim).

If you have time to try it out and feel like there is something that I can contribute from it, let me know.

[ashwinvis]

Since the markdown-it KaTeX plugin is not maintained and MathJax v3 is nearly as fast as KaTeX, I am inclined to close this issue and pursue #84