Rendering LaTeX in markdown

[arguiot]

As discussed in #1156 , LaTeX rendering inside a code block like:

$$
Equation
$$

Or $Equation$ would be an interesting feature to add, as Apple works on SwiftNumerics and Google on Tensorflow for Swift, many math libraries will start to appear.

This PR focuses on front end rendering, @johnfairh suggested to give control over generating the code element - so instead of <code>$equation$</code> it could give, for example, <span class="math">equation</span>. Then the selector is easier and the styling will be easier because there's no <code> element to fight with.

[arguiot]

Also, I'm not sure, but maybe we also should consider passing displayMode: true to KaTeX, since this will center the math on the page on its own line.

[arguiot]

The build is failing because it's comparing the output to a prebuilt version, so if you guys could update that so it succeed

[johnfairh]

Regexps: g flag is not required and will confuse with its lastIndex behaviour. Look at the s flag for the \n|.pattern? Missing ^$ anchors in the bigBlockRegex pattern?

Needs to not match in <pre><code> elements -- that is supposed to be verbatim.

Should test the bigBlockRegex first otherwise small will match (the accidental g flag sometimes saves it!)

Might be better to write a single regexp and use a capture group to pull out the equation to render: what's here gets confused by trailing newlines.

If katex fails then it would be good to fall back to what the user wrote - when I tried I just got blank content.

Style: looks to me as though this file uses semicolons, 2-space indent, and jQuery?

[johnfairh]

Thanks for looking at this! Added some javascript nits.

Jazzy docs are supposed to be offline which is how come they ship jQuery and so on.
KaTeX is heavy compared to what we have already, even if we don't ship any of the fonts, so I think to deploy this we'd have to make it opt-in and only copy the js/css/fonts into the docs if the flag is set.

Do you see what I mean about the <code> style? The gray background and h-padding are inherited from there:

I'll try a ruby patch in a bit to generate a span instead -- or a div for the $$ version, that way it'll naturally be a block and easy to style. I agree the $$ should be block & centered like mathoverflow.

Leave out the imagebot stuff - may be worthwhile but should be a different PR, just confusing this one.

To add some tests / make CI happier you need to:

1. fork jazzy_integration_specs (in the specs/integration_specs) directory
2. add your tests/demos to the misc_jazzy_features project
3. do bundle exec rake rebuild_integration_fixtures to update things, check they look right
4. commit those changes & set up a PR in the jazzy_integration_specs repo
5. git add spec/integration_specs to this PR and commit it -- this links the new version of the submodule to your PR.

[johnfairh]

Ok that came out easily enough -- https://gist.github.com/johnfairh/a82dc7cfc927491f31a3d213f8a4a52b
Feel free to tweak the styles etc. / critique my regexes :-)

[arguiot]

@johnfairh the regex looks good to me, I will test with my project and tell you if it works

[arguiot]

@johnfairh I'm having trouble running bundle exec rake rebuild_integration_fixtures.

So, I runned bundle exec rake swift_spec (and added a random function in MiscJazzyFeatures), but your ruby function codespan doesn't seem to have an effect on the final build.

I fixed a few things on the project:

• revert the ImgBot commit
• Copied a local version of KaTeX
• Fixed jazzy.js so it's compatible with your ruby function

[arguiot]

Oops, I might broke the build with that!

[johnfairh]

Hi @arguiot, the Ruby code is removing the $, and CSS class names need a dot in selectors. So the js should be something like:

// KaTeX rendering
document.querySelectorAll('.math').forEach((block) => {
  const content = block.innerHTML
  katex.render(content, block)
});

...which works for me on your fork, html:

<p>How about <span class='math m-inline'>\Gamma(n) = (n-1)!\quad\forall n\in\mathbb N</span> ?</p>

Results:

Yes, undo the Gemfile.lock change.

bundle exec rake swift_spec is a different command: it does not update the test results, it produces output in the jazzy/tmp directory -- I guess your changed files will be in there?

What is the trouble you are having with bundle exec rake rebuild_integration_fixtures ?

If you can add the tests, fix the styling (center/displaymode, anything else?), tweak error handling if possible, then I'll look after the "add a flag to avoid bloating every jazzy site with katex" part.

[arguiot]

@johnfairh Alright, I fixed the problem with bundle exec rake rebuild_integration_fixtures (it was a problem with my local version of ruby in fact) and submitted a new PR https://github.com/arguiot/jazzy-integration-specs . I also fixed the styling.

[johnfairh]

@arguiot -- just to let you know I'm not ignoring this, slowly working through the pieces.

[arguiot]

No problem

[johnfairh]

Continued in #1164.