Gollum: Gollum MathJax has different behavior for showing braces in inline vs display equations

[travisallison]

(1) The mathjax $ \{ x^2 \}$ does not show braces.

(2) The mathjax $ \\{ x^2 \\}$ does show braces.

(3) The mathjax $$ \{ x^2 \}$$ does show braces.

(4) The mathjax $$ \\{ x^2 \\}$$ does not show braces.

Is there a way to make it so that the inline equation in (1) will show braces as the display equation in (3) does?

(BTW, for math.stackexchange.com, (1) will display braces, while (2) will not.)

[dometto]

Is this a bug in gollum, or just a question about MathJax configuration? I don't have much experience with the latter so can't really tell. But if it's not gollum-specific, you're obviously better off asking on stack exchange!

[heavywatal]

In my environment, gollum with commonmarker gem generates HTML code as follows:

<p>(1) The mathjax $ { x^2 }$ does not show braces.</p>
<p>(2) The mathjax $ \{ x^2 \}$ does show braces.</p>
<p>(3) The mathjax $$ { x^2 }$$ does show braces.</p>
<p>(4) The mathjax $$ \{ x^2 \}$$ does not show braces.</p>

and MathJax renders it into this:

This behavior is correct and expected because escaping \{ \} to { } is defined in CommonMark spec. So, the answer to @travisallison's question

Is there a way to make it so that the inline equation in (1) will show braces as the display equation in (3) does?

is no. In other words, MathJax needs \{ \} in HTML to render { } in equations, and we have to write \\{ \\} in Markdown to get \{ \} in HTML from a decent markdown parser.

---

The true problems are the case (3) and (4) in the report:

(3) The mathjax $$ { x^2 }$$ does show braces.
(4) The mathjax $$ \{ x^2 \}$$ does not show braces.

These are not correct. I guess @travisallison is using the gollum's default github-markup, which may be doing something wrong with backslash escaping...?

[dometto]

Thanks for the clarification, @heavywatal! @travisallison, could you provide us with the output of gollum --versions (note the plural)? I also suspect you're using the default markdown renderer, i.e. kramdown.

[travisallison]

Thank you for investigating this @heavywatal and @dometto.

The results from gollum --versions

Gollum 5.0.1
Running on: x86_64-linux with Ruby version 2.7.0
Using:
rugged 0.99.0
gollum-rugged_adapter 0.99.6
gollum-lib 5.0.3
Markdown rendering gem: kramdown
Other renderering gems:
none

[heavywatal]

Thanks for the report. I confirmed the following HTML is generated with gollum+kramdown:

<p>(1) The mathjax $ { x^2 }$ does not show braces.</p>

<p>(2) The mathjax $ \{ x^2 \}$ does show braces.</p>

<p>(3) The mathjax <span class="kdmath">$\{ x^2 \}$</span> does show braces.</p>

<p>(4) The mathjax <span class="kdmath">$\\{ x^2 \\}$</span> does not show braces.</p>

and it results in the rendered equations as @travisallison reported first. I think this output is completely wrong from CommonMark/GFM's view point, but kramdown people may think this is expected and correct.

What is gollum's policy on markdown flavor? If it is completely neutral or conservative on the existing behavior, we can close this issue without any change. If it is leaning towards CommonMark/GFM, we should think about replacing the default parser/renderer.

[dometto]

The main reason why we adopted kramdown as defeault renderer is a) CommonMarker did not exist at the time :) and b) we want everything to install flawlessly on JRuby (also on Windows). The old github-markdown gem did not fulfill requirement b). But perhaps CommonMarker does?

[heavywatal]

CommonMarker is a thin wrapper of cmark-gfm written in C, which means it does not work with JRuby I guess... kramdown, on the other hand, is a pure ruby gem.

[travisallison]

@heavywatal, what is your environment? I installed commonmarker and my gollum --versions now is:

Gollum 5.0.1
Running on: x86_64-linux with Ruby version 2.7.0
Using:
rugged 0.99.0
gollum-rugged_adapter 0.99.6
gollum-lib 5.0.3
Markdown rendering gem: commonmarker
Other renderering gems:
none

But I am unable to render { inline with a single \.
The mathjax $ \{ x^2 \}$ does not display braces.

What's strange is that when I uninstall commonmarker and install githup-markdown so that markdown rendering gem is listed as github/markdown, I enter the following:

(1) The mathjax $ \{ x^2 \}$ does not display braces. (Braces are not displayed)
(2) <p>The mathjax $\{ x^2 \}$ does display braces.</p> (Braces are displayed because of the <p>)

When I view the page's source,
(1) is rendered as: <p>The mathjax $ { x^2 }$ does not display braces.</p>

(2) is rendered as <p>The mathjax $ \{ x^2 \}$ does display braces.</p>

I am not sure what is happening.

[heavywatal]

But I am unable to render { inline with a single \.
The mathjax $ { x^2 }$ does not display braces.

Like I said, $ \{ x^2 \}$ in markdown becomes $ { x^2 }$ in HTML, and MathJax will show you x^2.

(1) The mathjax $ \{ x^2 \}$ does not display braces. (Braces are not displayed)
(2) <p>The mathjax $\{ x^2 \}$ does display braces.</p> (Braces are displayed because of the <p>)

This behavior is reasonable and defined in CommonMark. See https://spec.commonmark.org/0.29/#html-blocks for how html tags are interpreted.

% bundle exec gollum --versions                           
NOTE: Gem::Specification#rubyforge_project= is deprecated with no replacement. It will be removed on or after 2019-12-01.
Gem::Specification#rubyforge_project= called from /Users/watal/fork/gollum-lib/gemspec.rb:13.
NOTE: Gem::Specification#rubyforge_project= is deprecated with no replacement. It will be removed on or after 2019-12-01.
Gem::Specification#rubyforge_project= called from /Users/watal/fork/gollum-lib/gemspec.rb:13.
Gollum 5.0.1
Running on: x86_64-darwin18 with Ruby version 2.7.1
Using:
rugged 0.99.0
gollum-rugged_adapter 0.99.6
gollum-lib 5.0.3
Markdown rendering gem: commonmarker
Other renderering gems:
none

[travisallison]

Thank you, @heavywatal. I now understand what you're point is.

[heavywatal]

Now that MathJax, CommonMarker, kramdown, and gollum are working as expected, shall we close this issue, @travisallison ?

Let's discuss the kramdown problem in a new thread if necessary.

[travisallison]

Yes, that's fine. Thanks to all for the help.

On Sun, Jun 14, 2020, 8:44 AM Watal M. Iwasaki [e-mail]
wrote:

Now that MathJax, CommonMarker, kramdown, and gollum are working as
expected, shall we close this issue, @travisallison
https://github.com/travisallison ?

Let's discuss the kramdown problem in a new thread if necessary.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/gollum/gollum/issues/1559#issuecomment-643784223, or
unsubscribe
https://github.com/notifications/unsubscribe-auth/ACWUMPUXWX45U3DUR2RW75LRWTV55ANCNFSM4MWE4VGQ
.