render math in README.org on github

render math in README.org on github

[Leo Butler]

Hello,

I am trying to use MathJax with a README.org file on github, but I am
having no luck. I believe that this "just works" with markdown on
github.

The best that I could find was a bug report by karthink [fn:1] that
refers to following instructions on a wiki. But, I can't find that wiki,
nor can I find any other advice that works. DuckDuckGo suggested an AI,
but that seems to be a source of infinitely many wrong guesses and about
as much frustration (it's like trying to get a straight answer out of a
C student).

Any pointers or tips would be appreciated.

TIA,
Leo

[fn:1] https://github.com/gollum/gollum/issues/1588

Re: render math in README.org on github

[Nikolaos Chatzikonstantinou]

[-- Attachment #1: Type: text/plain, Size: 1056 bytes --]

Do you want mathjax when viewing the readme file? If github is broken it is
on their end,  they don't have the best coverage of org features.

Or do you want mathjax in the generated html in a github pages? That can be
done...

Another place that org doesn't work (at all) is pypi.

On Fri, Dec 20, 2024, 12:26 PM Leo Butler <Leo.Butler@umanitoba.ca> wrote:

> Hello,
>
> I am trying to use MathJax with a README.org file on github, but I am
> having no luck. I believe that this "just works" with markdown on
> github.
>
> The best that I could find was a bug report by karthink [fn:1] that
> refers to following instructions on a wiki. But, I can't find that wiki,
> nor can I find any other advice that works. DuckDuckGo suggested an AI,
> but that seems to be a source of infinitely many wrong guesses and about
> as much frustration (it's like trying to get a straight answer out of a
> C student).
>
> Any pointers or tips would be appreciated.
>
> TIA,
> Leo
>
> [fn:1] https://github.com/gollum/gollum/issues/1588
>

[-- Attachment #2: Type: text/html, Size: 1535 bytes --]

Re: render math in README.org on github

[Leo Butler]

On Fri, Dec 20 2024, Nikolaos Chatzikonstantinou <nchatz314@gmail.com> wrote:

> Do you want mathjax when viewing the readme file?

Yes. The only documentation I have seen refers to markdown.

On a hunch, I changed all the math delimiters in my README.org to $ and
$$ and that worked. But, I would prefer to use the math delimiters \(\)
and \[\] and have that work.

> If github is broken it is on their end, they don't have the best
> coverage of org features.

I don't know enough about this to say what is broken. I am finding it
difficult to uncover good information about how things like this are
meant to work and how they can be configured.

Leo

>
> Or do you want mathjax in the generated html in a github pages? That can be
> done...
>
> Another place that org doesn't work (at all) is pypi.
>
> On Fri, Dec 20, 2024, 12:26 PM Leo Butler <Leo.Butler@umanitoba.ca> wrote:
>
>> Hello,
>>
>> I am trying to use MathJax with a README.org file on github, but I am
>> having no luck. I believe that this "just works" with markdown on
>> github.
>>
>> The best that I could find was a bug report by karthink [fn:1] that
>> refers to following instructions on a wiki. But, I can't find that wiki,
>> nor can I find any other advice that works. DuckDuckGo suggested an AI,
>> but that seems to be a source of infinitely many wrong guesses and about
>> as much frustration (it's like trying to get a straight answer out of a
>> C student).
>>
>> Any pointers or tips would be appreciated.
>>
>> TIA,
>> Leo
>>
>> [fn:1] https://github.com/gollum/gollum/issues/1588
>>

Re: render math in README.org on github

[Max Nikulin]

On 21/12/2024 01:51, Leo Butler wrote:
> On Fri, Dec 20 2024, Nikolaos Chatzikonstantinou wrote:
> 
>> Do you want mathjax when viewing the readme file?
> 
> Yes. The only documentation I have seen refers to markdown.
> 
> On a hunch, I changed all the math delimiters in my README.org to $ and
> $$ and that worked. But, I would prefer to use the math delimiters \(\)
> and \[\] and have that work.

I suggest to be realistic and to adjust your expectations. There have 
been no commits to <https://github.com/wallyqs/org-ruby> last years and 
GitHub does not use the latest release.

Use a kind of Pidgin Org that is compatible with both org-ruby and 
Emacs. If GitHub renders $...$ and $$...$$ then use it, despite they are 
going to be deprecated in Org.

<https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions>
<https://github.blog/news-insights/product-news/math-support-in-markdown/>

You may try to file a bug against <https://github.com/github/markup/> or 
some other project that really contains MathJax config to extend the 
list of supported math delimiters for Org files.

>> If github is broken it is on their end, they don't have the best
>> coverage of org features.

GitHub and GitLab just use org-ruby gem, they do not develop it.

org-ruby is more close to regexps used for fontlock than to 
org-element.el parser used for export. There are a lot of Org features 
that are not recognized by org-ruby. In particular, org-ruby is unaware 
of math (TeX) at all, it is just semi-transparent for this kind of 
constructs.

And finally, GitHub performs security audit before update of deployed 
gem version. Likely they will be reluctant to do it frequently pulling 
changes from a fork.

>> On Fri, Dec 20, 2024, 12:26 PM Leo Butler wrote:
>>
>>> The best that I could find was a bug report by karthink [fn:1] that
>>> refers to following instructions on a wiki. But, I can't find that wiki
[...]
>>> [fn:1] https://github.com/gollum/gollum/issues/1588

See the description of the project and its wiki. As to specific 
superscript issues, add

#+options: ^:nil

as a workaround.