Disabling LaTeX generation in Documenter Markdown

Documenter.jl is being used with the Markdown backend to process docstrings into .md files. Usually the next step would be to use MkDocs or something similar to turn them into .html files. Unfortunately, the system where this is running is fairly locked down and MkDocs can’t be used. The src files are on a Gitlab server, but Gitlab Pages is disabled (which is why we’re using the Markdown backend in the first place).

Gitlab formats the .md files nicely, but there is one problem. The source code docstrings have a considerable number of math blocks, e.g.

    \alpha = \frac{1}{2}

which become

$$\alpha = \frac{1}{2}$$

after processing by Documenter.jl. Gitlab automatically renders the ```math block correctly but doesn’t format the $$ style.

How can I prevent Documenter.jl from changing the math formatting in the generated .md files?

1 Like

This is a bit of a hack, but what you could do is re-define the relevant Markdown stdlib methods in make.jl. I haven’t tested it, but I think, for the block math, this is where the dollar signs come from:

Of course, this is all internals, so there is no guarantee that updating the version of Julia or Documenter won’t break things.

Just curious: does it actually render them as math? Or does it just show the LaTeX source?

Edit: I also found the method that renders the inline LaTeX:

1 Like

Thanks for pointing this bit out.

We’ve ended up just writing some code to identify the dollar signs and replace them with ```math.

It actually renders as math! See https://docs.gitlab.com/ee/user/markdown.html#math

I was surprised that Gitlab does this too. (We also added some code to switch the single dollar signs to Gitlab-compatible $` `$).