LaTeX syntax support in wiki

[guyansrg]

• Gitea version (or commit ref): 1.3.2
• Git version: 2.15.0
• Operating system: Windows 7
• Database (use [x]):
  • PostgreSQL
  • MySQL
  • MSSQL
  • SQLite
• Can you reproduce the bug at https://try.gitea.io:
  • Yes (provide example URL)
  • No
  • Not relevant
• Log gist:

Description

It seems that gitea does NOT support LaTeX syntax in wiki.
Are there any suggestions for solving this problem?

[sapk]

Hi,
You can use external rendering implemented in #2570 and documented here. With that you can setup your LaTex environnement and make gitea call it.

[guyansrg]

Thank you for your answer.
I'm not sure I can solve it by myself.
I hope there has an offical solution for this problem.

[kellpossible]

I have a feeling perhaps this issue is low priority, especially when it should be possible to implement a solution with the external markup api. You should at least give it a try! (and ask question here if you have trouble)

[leleobhz]

Hello folks!

About LaTeX support, its possible to allow https://github.com/mathjax/MathJax to be inserted as render? MediaWiki does have https://www.mediawiki.org/wiki/Extension:SimpleMathJax and AFAIK is not that bad to add a option to enable MathJax loading in Wiki section and use it to parse the $$ flags.

Thanks!

[leleobhz]

P.s: I made a tiny Dockerfile to install asciidoc - if someone needs it:

FROM gitea/gitea:latest

RUN apk add --update asciidoc && \
        rm -rf /var/cache/apk/*

[leleobhz]

P.s 2: Can be used some engine like https://upmath.me/ ?

[thehowl]

upmath itself requries some PHP for the backend. Using upmath as an external service is not an option (we're aiming for self-hosting). But eventually implementing MathJax definitely sounds great, although something that does not depend on JS sounds even better, although it might be less feasible :)

[leleobhz]

Hello @thehowl !

But math w/o JS can be only made with backend software and images - like Wikipedia does - but its not convinient for cientific applications - for example, as I intent to use. Can this be a choose?

Also, I'm not a skilled developer, but if I can help with something to support MathJax, for me its a great pleasure.

Thanks!

[thehowl]

Hmm. Keep in mind that Gitea Wikis are really meant for documentation and not really for math, while I understand your use case. If anything, I would suggest using .tex files in a repository with a custom render that plugs in MathJax, but I'm not quite sure if adding a markdown extension for maths is worth it when it comes to gitea.

[leleobhz]

Hello @thehowl !

I know, but for some simple scientific projects, MathJax will be enough. Maybe the support can come as a generic support, fitting the example in https://docs.mathjax.org/en/latest/start.html of the following:

<script type="text/javascript" async
  src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

So if Gitea allows to use custom html before the markdown parser page, it may help with the issue - not only allowing MathJax, but another JS parsers/features. This also allow the user to fit the interface in a easier way than editing the source of Gitea for simple operations.

Thanks!

[lafriks]

You could include this in custom template (see docs - customizing Gitea)

[thehowl]

(keep in mind though that @lafriks solution only works on 1.4, so you'll have to use the rc release for now)

[lunny]

@sapk that implementation will only affect files but not wikis. We needs some work based that for wiki support.

[sapk]

I think a good solution could be to put in contrib a Dockerfile example of gitea with external rendering and put it under contrib folder (I could try something). Even more do a article or docs that explain how to do it.

[sapk]

[leleobhz]

Support for LaTeX in markdown files inside Git helps me, since I can use the markdown + mathjax support inside wiki. I'm using this to create the documentation of a project, so a Wiki or a -doc repository does not differ for me. But Wiki support is a beautiful way to go.

I vote for mathjax support since its a easier and beauty way to parse math, add support for screen readers - as mathjax supports formats for blind readers and etc.

[laoshaw]

same here, it will be great if gitea supports mathjax (or even katex), very useful feature

[Eisfunke]

Using pandoc as an replacement external renderer for markdown you can support TeX math with KaTeX/MathJax/... in markdown with gitea.

Just install pandoc and add this to your app.ini (see here):

[markup.markdown]
ENABLED = true
FILE_EXTENSIONS = .md,.markdown
RENDER_COMMAND = "pandoc -f markdown -t html --katex"

And in your custom/templates/custom/header.tmpl (see here):

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-D+9gmBxUQogRLqvARvNLmA9hS2x//eK1FhVb9PiU86gmcrBrJAQT8okdJ4LMp2uv" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-483A6DwYfKeDa0Q52fJmxFXkcPCFfnXMoXblOkJ4JcA8zATN6Tm78UNL72AKk+0O" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-yACMu8JWxKzSp/C1YV86pzGiQ/l1YUfE8oPuahJQxzehAjEt2GiQuy/BIvl9KyeF" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>

This is the standard KaTeX inclusion code from https://github.com/Khan/KaTeX (You can of course put the KaTeX files in your custom/public directory (or anywhere else where they get served) and reference those instead of using the cdn).

This works for markdown-files in repos and in wikis. The latter currently gives an error message due to a bug which I just fixed in PR #4863.

mathjax should work just the same, Pandoc supports it as well, but I didn't try that out. Check out their manual. Pandoc has a few other html math options described there that might be worth looking at.

---

On another note, adding math syntax support is not part of gitea, but rather of blackfriday, the markdown processor gitea uses. See this PR. There is a ongoing discussion about that over there.

[dymaxionkim]

I am inspired by Mr.Eisfunke's comment.
so I tried to enable MathJax like that ;

.../templates/custom/header.tmpl

<!--  MathJax  -->
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    tex2jax: {
      inlineMath: [ ['$','$'], ["\\(","\\)"] ],
      processEscapes: true
    }
  });
</script>
<script src="//cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

This is my header.tmpl file.

I think it works well. --> A wIki page for MathJax test in Gitea
Thank you!

[AlphaJack]

I got it working with KaTeX without server side rendering by simply adding

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"></script>
<!--The following is needed to render inline math delimited by single "$"-->
<script>
      document.addEventListener("DOMContentLoaded", function() {
          renderMathInElement(document.body, {
              delimiters: [
                {left: "$$", right: "$$", display: true},
                {left: "$", right: "$", display: false}
              ]
          });
      });
</script>

to /var/lib/gitea/custom/templates/custom/header.tmpl.

I tested the following code:

# This is a test

**Definition 1.1.** Given the human set $H$, we call "fun" the function
$$\begin{array}{rccl}\mathscr{S} \colon & H & \to & \{0, 1\} \times \{0, 1\} \times \{0, \frac{1}{2}, 1\} \\\ & h & \mapsto & (e(h), x(h), g(h))\end{array}$$ 
where $e(h)$ value is 0 if $h$ started as A and 1 if $h$ started as B.

**Definition 1.2.** Let $h \in X$ be an element of the set $U$ [...]

$${\mu}_{t} = {\rho} {C} _ {\mu} {\frac{k^2}{\epsilon}}$$

$$T^1_{0} = \begin{bmatrix} C_1  &  0  &  -S_1  &  a_1 C_1 \\\ S_1  &  0  &  C_1  &  a_1 S_1 \\\ 0  &  -1  &  0  &  d_1 \\\ 0  &  0  &  0  &  1 \end{bmatrix}$$

[laoshaw]

yes this works :) I put the script portion to footer.tmpl instead of header.tmpl though to be safer

[joyqat]

I use the following code in footer.tmpl:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha256-tn6hZ2YGDv0w1/DaFL4MiUoXuAVclrtFZs13ch3TB9M=" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha256-1qhJwAgsSPVSSjlQVTewHS49eaoAbOz651dveUANVBI=" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha256-oEuQVLwO5Ii6subChtLbrY5gx7NDRU+UJJ9jvvau+FI=" crossorigin="anonymous"></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
        document.querySelectorAll(".markdown").forEach(function(elem) {
            renderMathInElement(elem, {
                delimiters: [
                {left: "$$", right: "$$", display: true},
                {left: "$", right: "$", display: false}
                ]
            });
        })
    });
</script>

By set ENABLE_HARD_LINE_BREAK_IN_COMMENTS to false, latex in issues and prs can also be rendered. ref: https://docs.gitea.io/en-us/config-cheat-sheet/#markdown-markdown

[joyqat]

Since gitea now uses goldmark, I think https://github.com/litao91/goldmark-mathjax could be used for rendering latex.

[zeripath]

That unfortunately would reguire recompilation or for MathJax to be included & distributed with gitea

[Y0ngg4n]

For everybody comming to this issue and searching for a solution.
I have used @joyqat code and got it working.

So a short tutorial how it works:
Go to your data directory of gitea.
So for example if you use the docker container check in what directory you mount the /data directory of the docker container.
So as example if you are using docker-compose you will have something like this:

volumes:
      - /opt/docker/volumes/gitea:/data # <---- You need this
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

So in my example the container data is in /opt/docker/volumes/gitea.

• Now go to that directory: cd /opt/docker/volumes/gitea
• Go to the gitea directory: cd gitea
• If you ls -la you will see some file structure like this:

ls -la
total 44
drwxr-xr-x 11 1001 1001 4096 Jun  1 10:44 .
drwxr-xr-x  5 root root 4096 Apr 27 20:11 ..
drwxr-xr-x  2 1001 1001 4096 Sep 27  2020 attachments
drwxr-xr-x  3 1001 1001 4096 Apr 27 13:18 avatars
drwxr-xr-x  2 1001 1001 4096 Jun  1 10:42 conf
drwxr-xr-x  4 1001 1001 4096 Apr 27 16:16 indexers
drwxr-xr-x  2 1001 1001 4096 Jun  1 00:00 log
drwxr-xr-x  9 1001 1001 4096 May 29 15:05 queues
drwxr-xr-x  2 1001 1001 4096 Oct 21  2020 repo-avatars
drwx------ 15 1001 1001 4096 Apr 27 15:08 sessions

• Edit your app.ini: nano conf/app.ini
• Add this to the bottom:

[markdown]
ENABLE_HARD_LINE_BREAK_IN_COMMENTS = false

• Save the file
• Create a templates directory: mkdir -p templates/custom
• Go to this website: Katex autorender
• Copy the second code block, so when i write this it looks like this:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-YNHdsYkH6gMx9y3mRkmcJ2mFUjTd0qNQQvY9VYZgQd7DcN7env35GzlmFaZ23JGp" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-vZTG03m+2yp6N6BNi5iM4rW4oIwk5DfcNdFfxkk9ZWpDriOkXX8voJBFrAO7MpVl" crossorigin="anonymous"></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {
          // customised options
          // • auto-render specific keys, e.g.:
          delimiters: [
              {left: '$$', right: '$$', display: true},
              {left: '$', right: '$', display: false},
              {left: '\\(', right: '\\)', display: false},
              {left: '\\[', right: '\\]', display: true}
          ],
          // • rendering keys, e.g.:
          throwOnError : false
        });
    });
</script>

• Create the footer template: nano templates/custom/footer.tmpl
• Paste the copied code and save the file
• Restart your Gitea Server

If you use Nginx with Content Security Policies you need to add https://cdn.jsdelivr.net to script-src, font-src and style-src.

[silverwind]

It's not only about wiki, but all Markdown content, right?

GitHub has recently added MathJax.

[Y0ngg4n]

exactly. all markdown content.

[silverwind]

Is there a verdict of whether MathJax or Katex is the "better" renderer? Any pro/cons? GitLab uses Katex, GitHub MathJax.

[eeyrjmr]

Is there a verdict of whether MathJax or Katex is the "better" renderer? Any pro/cons?

https://www.intmath.com/cg5/katex-mathjax-comparison.php
MathJax might be more complete w.r.t Latex syntax which might be of importance for Jupyter and co but for a problem report?

Also there are several unsupported escapes in Katex
https://katex.org/docs/support_table.html

Also I just added katex to my test gitea and there is an odd quirk if you edit a markdown cell... the auto-render bracers are replaced when you proceed to edit (this might just be due to it being a 3rd class citizen in gitea )

--edit--
just tried mathjax, it also suffers from the auto-render bracers being changed when you edit in gitea (something up with gitea...) but it does render and it is visibly slower so a large set of latex could be a visual distraction

[eeyrjmr]

Correction... it wasn't gitea, it was some configuration... once guards are used \$ e^{ix} = cos x + i sin x \$ both katex and mathjax works well

Katex is fast and it is only missing some esoteric dialect

[zeripath]

If this is actually wanted I can dust off a branch that adds katex support to goldmark.