Bad MathJax/markdown interactions

[robertylewis]

Putting the line what if I put $f[a,b](cd)$ in tex? $g_{x}(y)$ ? in a markdown file/block produces:

I'm not sure if/how I can disable markdown processing between delimiters using markdown2.

cc @glangmead

[gebner]

Oh, f[a,b](cd) is a Markdown link... I guess this is why gitlab uses $`a^2+b^2=c^2`$: https://docs.gitlab.com/ee/user/markdown.html#math

[glangmead]

I think I see. We want markdown2 to be hands-off between the math delimiters just like we want mathjax to be hands-off outside them. I see two solutions: find a markdown library that supports this, or submit a patch to markdown2 to add another "extra" that does this. I've spent a few minutes looking into the latter and can only say that it seems doable. In spirit it should be similar to its logic for handling backticks, since it's also hands-off between those.

[glangmead]

See _do_code_spans at https://github.com/trentm/python-markdown2/blob/master/lib/markdown2.py

[glangmead]

Here's a python markdown library that appears to support ignoring what's between math delimiters: https://github.com/FSX/misaka

[jcommelin]

Doesn't pandoc do the right thing as well? https://pandoc.org

[glangmead]

I had success with your example @robertylewis by changing print_docs.py as follows:

pip install misaka

then near the top of the script instantiate the global markdown converter object:

import misaka
markdown_to_html = misaka.Markdown(misaka.HtmlRenderer(), extensions=('math', 'math-explicit',))

and use markdown_to_html() where you call markdown2 now. It's important to specify both 'math' and 'math-explicit', as I learned after too much trial and error.

You configured markdown2 to do some other things with its extras, namely 'doc' and ['code-friendly', 'cuddled-lists', 'fenced-code-blocks', 'link-patterns']. I haven't looked up how to do those with misaka. Internally it's using something called hoedown which is another place to learn how it works.

https://github.com/hoedown/hoedown/

[glangmead]

Oh AND, misaka converts the dollar signs into \(..\) and double-dollars into \[..\] so we need to reintroduce those as allowable for mathiax.

In the python that means quadruple backslashes:

          tex: {{
            inlineMath: [['$', '$'], ['\\\\(', '\\\\)']],
            displayMath: [['$$', '$$'], ['\\\\[', '\\\\]']]
          }},

[glangmead]

@robertylewis What's the right way to test doc-get locally and have it look like the live site which has frames and css and things? The html/ directory I get from running gen_docs looks bare-bones when I open it locally.

I may have a little time in the next few days to investigate switching to misaka, but I'd like to get a faithful version of the site so I can double-check the impact of markdown2's code-friendly, cuddled-lists, etc.

[robertylewis]

Yesterday I added a few comments at the bottom of the https://github.com/leanprover-community/doc-gen readme. With the 3.5.1 upgrade, I think it's pretty painless:

leanpkg configure
update-mathlib
gen_docs -l
cd html
python3 -m http.server

then open localhost:8000 in your browser. -l isn't necessary unless you're playing with the CSS.

I'm guessing the css issue you're having is because you aren't running the server. If you don't want to do that, you can also edit localhost:8000 in the python script to be a path on your computer.

[bryangingechen]

Continuing the discussion from leanprover-community/mathlib#3776 here... @gebner said:

I believe the standard markdown-conforming solution is $`x \leadsto y`$, which is also used by gitlab. https://docs.gitlab.com/ee/user/markdown.html#math

Hmm, I don't think I've ever seen this before. Most of my experience mixing markdown and LaTeX is from writing MathOverflow posts which somehow "just work". This math.stackexchange page (which presumably uses the same setup) shows a bunch of examples. I think this is in line with @robertylewis's opinion that we shouldn't force people to use "malformed" markdown.

[gebner]

This should be fixed now by #110