Render mathematical expressions in Markdown On GitHub(github.blog)
github.blog
Render mathematical expressions in Markdown On GitHub
https://github.blog/changelog/2022-05-19-render-mathematical-expressions-in-markdown/
113 comments
If I was building this feature, I'd also pick client side rendering, simply because at GitHub's scale, rendering on the server side will require a bunch of servers, which will need to be managed and looked after.
By offloading the rendering to the client, you make use of the spare capacity that exists on most client machines today, with no noticable slowdown for the user (it may even end up doing the "first paint" faster in the browser if GitHub are careful about their implementation).
Even with my SaaS product, we try and do as much work on the client as possible to reduce our server requirements. If you're sensible about it, users don't even notice.
By offloading the rendering to the client, you make use of the spare capacity that exists on most client machines today, with no noticable slowdown for the user (it may even end up doing the "first paint" faster in the browser if GitHub are careful about their implementation).
Even with my SaaS product, we try and do as much work on the client as possible to reduce our server requirements. If you're sensible about it, users don't even notice.
> while no noticable slowdown for the user (it may even end up doing the "first paint" faster in the browser if GitHub are careful about their implementation).
Have you visited math.stackexchange? Pop by their MathJax reference page[0], and observe how long all the mathematical notation takes to render fully—it takes at least six seconds on my recent notebook, plugged in. On my 2018 iPad Pro, it takes well over thirty seconds on the first page load (drops to ~5 s on subsequent visits: there's probably some caching going on).
Here's[1] a benchmark comparing KaTeX (server-side), MathJax 2.7, and MathJax 3.0 (apparently a complete rewrite supporting server-side rendering[2], but it's still noticeably slower than KaTeX).
MathJax is really slow (slower still than LaTeX itself, and that's saying something).
[0]: https://math.meta.stackexchange.com/questions/5020/mathjax-b...
[1]: https://www.intmath.com/cg5/katex-mathjax-comparison.php
[2]: https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.h...
Have you visited math.stackexchange? Pop by their MathJax reference page[0], and observe how long all the mathematical notation takes to render fully—it takes at least six seconds on my recent notebook, plugged in. On my 2018 iPad Pro, it takes well over thirty seconds on the first page load (drops to ~5 s on subsequent visits: there's probably some caching going on).
Here's[1] a benchmark comparing KaTeX (server-side), MathJax 2.7, and MathJax 3.0 (apparently a complete rewrite supporting server-side rendering[2], but it's still noticeably slower than KaTeX).
MathJax is really slow (slower still than LaTeX itself, and that's saying something).
[0]: https://math.meta.stackexchange.com/questions/5020/mathjax-b...
[1]: https://www.intmath.com/cg5/katex-mathjax-comparison.php
[2]: https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.h...
On my machine the first link loaded in under a second. On my mobile it was about 3 seconds, but it didn't feel especially sluggish. Even then, I'd say stackexchange has a somewhat inefficient implementation, in that they're trying to render everything in one shot.
For example, I see no reason why they wouldn't just render the stuff that's in view first, and the rest is rendered incrementally as the user scrolls, or a few seconds after the initial paint.
I take your point that KaTeX is faster in absolute terms, but from a usability point of view, the benefits do not outweigh the costs in my opinion.
For example, I see no reason why they wouldn't just render the stuff that's in view first, and the rest is rendered incrementally as the user scrolls, or a few seconds after the initial paint.
I take your point that KaTeX is faster in absolute terms, but from a usability point of view, the benefits do not outweigh the costs in my opinion.
> the first link loaded in under a second. On my mobile it was about 3 seconds
Did you wait for the typefaces to change to Computer Modern? On my smartphone, this took ages, and that is what I implied by 'fully loaded'; more complex maths is unreadable on some devices with only the native typefaces. Even a (relatively straightforward) cube root doesn't look clean[0].
MathJax has (from my observation) two 'levels' of rendering, where it uses the OS native typeface for a first pass, and then renders everything in Computer Modern for a uniform look (except on Apple devices, which somehow override this with STIX fonts).
Needless to say, the typeface change means that the dimensions of the maths content change, causing the rest of the website to reflow a second time. This second render takes the bulk of the time, and having a website's content unexpectedly jump around a long while after it has (apparently) loaded is not exactly user-friendly.
[0]: https://imgur.com/a/CrKqeI5
Did you wait for the typefaces to change to Computer Modern? On my smartphone, this took ages, and that is what I implied by 'fully loaded'; more complex maths is unreadable on some devices with only the native typefaces. Even a (relatively straightforward) cube root doesn't look clean[0].
MathJax has (from my observation) two 'levels' of rendering, where it uses the OS native typeface for a first pass, and then renders everything in Computer Modern for a uniform look (except on Apple devices, which somehow override this with STIX fonts).
Needless to say, the typeface change means that the dimensions of the maths content change, causing the rest of the website to reflow a second time. This second render takes the bulk of the time, and having a website's content unexpectedly jump around a long while after it has (apparently) loaded is not exactly user-friendly.
[0]: https://imgur.com/a/CrKqeI5
I wonder about your setup. On an iPhone 12 on residential wifi behind a VPN, I noticed no lag, delayed rendering, or weird rendering issues.
I can confirm that MathJax is very slow, especially if you render complex math including graphs (all in view). The Google Lighthouse Benchmark gave me a very bad performance score, but as soon as I switched to Katex my statically rendered blog gets 95-100 points for performance.
> [...] observe how long all the mathematical notation takes to render fully—it takes at least six seconds on my recent notebook, plugged in.
Does this really matter though? When I've encountered math-heavy pages that have been slow to fully render the math has also been slow for my brain to processes. As long as the math rendering is faster than my brain's math understanding it has been fine.
Does this really matter though? When I've encountered math-heavy pages that have been slow to fully render the math has also been slow for my brain to processes. As long as the math rendering is faster than my brain's math understanding it has been fine.
On my iPad Pro (2018), the first page rendered fully within seconds. I’d never visited the page before. I scrolled down and up the entire page to check.
On my mobile, for [1] KaTex loads in 900ms, MathJax in 1200-1600ms. Good enough for client side usage.
The tradeoff is exactly noticeable slowdown: https://imgur.com/a/y47haf9. Browser JS engines are single threaded, so MathJax has to wait its turn behind more important scripts, and it gets worse with slower devices and networks. It's a contest of download vs execution time, which a 2KB pre-rendered image will always win.
You're right on the money with the server costs though.
You're right on the money with the server costs though.
> Browser JS engines are single threaded
The JS interpreter is single threaded. But, you can offload the work to a web worker, that runs another instance of the interpreter in a separate thread.
Also for rendering LaTex it’s possible to optimize the rendering algorithm using WASM.
I’m not saying that MathJax does that, or it has good performance. But, there are options to optimize the client side rendering.
The JS interpreter is single threaded. But, you can offload the work to a web worker, that runs another instance of the interpreter in a separate thread.
Also for rendering LaTex it’s possible to optimize the rendering algorithm using WASM.
I’m not saying that MathJax does that, or it has good performance. But, there are options to optimize the client side rendering.
Workers lack document access and have to schedule updates with the main thread. That puts us back where we started (plus the overhead of starting the web worker).
I don't know enough about the state of WASM today to say the same. Circa 2018 I know that it lacked DOM manipulation.
(In some distant year I will figure out the incantation to avoid getting sniped when talking about this stuff. I think I rewrote that line 4 times.)
I don't know enough about the state of WASM today to say the same. Circa 2018 I know that it lacked DOM manipulation.
(In some distant year I will figure out the incantation to avoid getting sniped when talking about this stuff. I think I rewrote that line 4 times.)
It doesn't put you back where you started at all. One thread aggregating the results from other workers and applying them to the DOM is not at all the same as a single thread doing all that work on its own.
Let me rephrase: distributing work to web workers won’t be faster in first page load than images in this conversation.
Because we have to participate in the main thread either way, prerendered images will always paint faster. There is simply too much action in the thread during the initial GitHub page lifecycle. The 40-50ms (~one long task) cost of spinning up a new web worker just solidifies that.
Because we have to participate in the main thread either way, prerendered images will always paint faster. There is simply too much action in the thread during the initial GitHub page lifecycle. The 40-50ms (~one long task) cost of spinning up a new web worker just solidifies that.
Sorry, but I find this approach very rude to your customers. It's kinda your job to make it work on your side and don't transfer the burdens to clients.
I don't know what your SAAS does (maybe it's not really applicable here), but in the case of github, it's very wastefull. Yes, it would take some work, some servers, etc but they have the skill, the money and everything they need to do it. They could do it once (well, with every change, but it's not very often) on their side instead every client on every pageview will have to do the same work again and again, wasting time and energy.
I don't know what your SAAS does (maybe it's not really applicable here), but in the case of github, it's very wastefull. Yes, it would take some work, some servers, etc but they have the skill, the money and everything they need to do it. They could do it once (well, with every change, but it's not very often) on their side instead every client on every pageview will have to do the same work again and again, wasting time and energy.
Interesting point of view, but I feel you're missing the point.
Do you find all native applications rude to customers?
Do you find all native applications rude to customers?
No. I'm absolutely expecting local native app to do all the work, it makes sense. With SAAS running in the browser I expect all the heavy lifting is done somewhere else...you know, as a service.
Historically client-side rendering has been a big headache. Not sure if it's improved recently, but avid math bloggers and blog readers will remember the problems of the past decade.
I would probably pretender it.
Why?
Because markdown files seldom change and probably read much more often.
Anyway I would not agree that it is a good idea to move everything to client just because you can. There are always up and downsides.
I think your comment is too generic.
Why?
Because markdown files seldom change and probably read much more often.
Anyway I would not agree that it is a good idea to move everything to client just because you can. There are always up and downsides.
I think your comment is too generic.
For pages with lots of mathematics markup, it is far better (in terms of download size) to send the latex markup and the katex library to the browser, and render it there. I tried rendering the mathematics server-side using katex on my own website a while ago, and the div soup generated by katex takes up loads of space.
Original page (compressed): 10 kB
Page with server-rendered Katex (compressed): 50 kB
Katex.js (compressed): 80 kB
So after two pages it’s a net win to not render the mathematics server-side.
Original page (compressed): 10 kB
Page with server-rendered Katex (compressed): 50 kB
Katex.js (compressed): 80 kB
So after two pages it’s a net win to not render the mathematics server-side.
For my blog (e.g. https://daniel.lawrence.lu/blog/y2021m09d08/ with tons of math), I render the math serverside using MathJax and serve them as SVG images (with alt text for the visually impaired). They get cached too which is nice especially since many symbols are duplicated. Seems fast enough for me.
You're being modest. This is easily the most performant option... although it means losing interactivity (right clicking equations on GitHub allows copy to clipboard, A11y features, etc).
Running the JS client side, like GitHub, means blocking the thread. You're either going to be 1. delaying other JS from running, or 2. rendering late, shifting the layout – which is what GitHub has chosen: https://imgur.com/a/y47haf9
(Sending the rendered div's is a non-starter. Large document sizes delay domContentLoaded, slow down browsers, aren't shared cacheable resources, etc.)
Your approach, then. On your page there are 178 SVGs. Total gzipped size is 490KB. SVGO[0] gets that down to 311KB – that's 1.74KB transferred per equation. These are non-blocking, immutable, cacheable assets. Brilliant.
Upgrades:
- Figure out viewbox and inline height/width values on the HTML so no layout jank (aka "Cumulative Layout Shift"/CLS) occurs. Unsure if this is possible for inline math.
- Add `loading="lazy"` afterwards. Users that don't scroll the entire length of the page won't suffer unneeded downloads, and the inlined sizes will prevent late CLS for those that do.
- Maybe re-add interactivity? Cheap option: just support copying alt-text in a context menu.
[0] https://github.com/svg/svgo
Running the JS client side, like GitHub, means blocking the thread. You're either going to be 1. delaying other JS from running, or 2. rendering late, shifting the layout – which is what GitHub has chosen: https://imgur.com/a/y47haf9
(Sending the rendered div's is a non-starter. Large document sizes delay domContentLoaded, slow down browsers, aren't shared cacheable resources, etc.)
Your approach, then. On your page there are 178 SVGs. Total gzipped size is 490KB. SVGO[0] gets that down to 311KB – that's 1.74KB transferred per equation. These are non-blocking, immutable, cacheable assets. Brilliant.
Upgrades:
- Figure out viewbox and inline height/width values on the HTML so no layout jank (aka "Cumulative Layout Shift"/CLS) occurs. Unsure if this is possible for inline math.
- Add `loading="lazy"` afterwards. Users that don't scroll the entire length of the page won't suffer unneeded downloads, and the inlined sizes will prevent late CLS for those that do.
- Maybe re-add interactivity? Cheap option: just support copying alt-text in a context menu.
[0] https://github.com/svg/svgo
> Figure out viewbox and inline height/width values on the HTML so no layout jank (aka "Cumulative Layout Shift"/CLS) occurs. Unsure if this is possible for inline math.
That's a great idea, I should do that. Right now I apply the height and offsets from the SVG file (via vertical-align and height) so that it flows nicely but I should add width too. It is trivially doable since the SVG does contain the width.
e.g.
That's a great idea, I should do that. Right now I apply the height and offsets from the SVG file (via vertical-align and height) so that it flows nicely but I should add width too. It is trivially doable since the SVG does contain the width.
e.g.
<img src="//daniel.lawrence.lu/texcache/683524188b1547a2a4466541ff07f2d6f83f599bi.svg" alt="\mathbf R(\mathbf T)" style="vertical-align: -0.838ex;height:2.843ex;">[deleted]
[deleted]
I used to think KaTeX was far superior to MathJax but now I'm not so sure. I made https://mk12.github.io/web-math-demo/ to compare them and other things. They're definitely superior to browser MathML rendering today, which is nonexistent in Chrome (though see https://mathml.igalia.com/), quite bad in Safari, and OK in Firefox. It's true pre-rendering KaTeX produces a lot of markup, but it compresses very well so I don't think it's a big deal. They both have MathML for accessibility, but MathJax is more flexible in letting the user right-click and change the rendering engine, view raw TeX, etc. Rendering KaTeX on the client side is faster than MathJax, but in my experience KaTeX is slightly worse quality, e.g. https://github.com/KaTeX/KaTeX/issues/3400 has gone unfixed for a long time.
There's currently around 100 LaTeX functions listed as "Not supported" in the Katex docs at https://katex.org/docs/support_table.html I've been trying hard for a while with my site (https://cocalc.com) to use only katex, but that's definitely never going to happen. Users frequently hit missing functionality, e.g., they have lots of notebooks that use "\mbox", so it's critical to support full mathjax. I currently do this by attempting to use katex, then falling back to mathjax if it fails. That said, as you point out, mathjax has massively improved over the last few years with mathjax3! Thanks for pointing out the quality issues, which I hadn't thought about.
> https://github.com/KaTeX/KaTeX/issues/3400 has gone unfixed for a long time.
I don't think I'd qualify an issue from the end of last year as "unfixed for a long time".
I don't think I'd qualify an issue from the end of last year as "unfixed for a long time".
Sorry I posted the wrong issue, it’s actually a duplicate of https://github.com/KaTeX/KaTeX/issues/3168 which was filed last August. I guess it’s not that long, but it was annoying for my use of KaTeX on https://mitchellkember.com/notes4u where I see it frequently. For example it affects \left\lvert\vec{b}\right\rvert which is a pretty simple piece of TeX I’d expect to render fine.
The last I knew, KaTeX had issues with accessibility. But honestly it is probably just best to ship raw MathML, translated from LaTeX on the server, and use MathJax as a polyfill for Chrome and Edge users. That way you get extremely fast rendering in Safari and Firefox without any extra javascript, and eventually Chrome will catch up.
I wouldn’t recommend relying on Safari MathML rendering today for anything but very basic equations. Firefox is a lot better, but still not quite at MathJax quality. I made a demo here https://mk12.github.io/web-math-demo/ that lets you compare them. Also if you edit the MathML markup box, it will render directly from that, just like the poly fill (sometimes the layout shifts slightly when switching from TeX -> MathJax HTML+CSS to TeX -> MathML -> MathJax HTML+CSS).
Nice demo. I don’t have access to a mac so I can’t see this in Safari, but using Firefox I can immediately spot there are some kerning mistakes in the MathML rendering which are not present in MathJax rendering.
However, isn’t that just the fact the the default math font (DejaVu Math TeX Gyre in Firefox i-on Ubuntu) is not good enough? I use Libertinus Math in my own little demo page (https://runarberg.github.io/mathup/) and it looks just fine (IMO). The only think to note is that TeX Gyre is so pervasive (as it is the default [only?] MathJax font) that it takes a bit getting used to other math fonts on the web.
For example here is the Iglalia example from your demo page displayed with Libertinus Math in Firfox (https://imgur.com/q3QuJOA). The same example has some issues in your demo page with DejaVu Math TeX Gyre
However, isn’t that just the fact the the default math font (DejaVu Math TeX Gyre in Firefox i-on Ubuntu) is not good enough? I use Libertinus Math in my own little demo page (https://runarberg.github.io/mathup/) and it looks just fine (IMO). The only think to note is that TeX Gyre is so pervasive (as it is the default [only?] MathJax font) that it takes a bit getting used to other math fonts on the web.
For example here is the Iglalia example from your demo page displayed with Libertinus Math in Firfox (https://imgur.com/q3QuJOA). The same example has some issues in your demo page with DejaVu Math TeX Gyre
> I'm sure they had their reasons
They do, accessibility being one of them. Rendering math in the way you describe makes it difficult, or impossible, to understand for all sorts of audiences, including those relying on screen reading software.
They do, accessibility being one of them. Rendering math in the way you describe makes it difficult, or impossible, to understand for all sorts of audiences, including those relying on screen reading software.
KaTeX includes hidden MathML for screen readers.
https://github.com/KaTeX/KaTeX/issues/38
https://github.com/KaTeX/KaTeX/issues/38
Our GitLab docs state "Math written in LaTeX syntax is rendered with KaTeX" https://docs.gitlab.com/ee/user/markdown.html but I'm not sure it isn't just using MathJax under the hood.
MathJax can do server side rendering too now!
Maths don't scale up. Moore's Law will catch up and eventually rendering math will be like rendering jpg. For now the priority is to get things to work so we don't waste extra time determining if we just avoid math or we use stupid PNG.
I'm so happy that I can just paste my definitions from latex preamble into a paragraph to include all the calitographic symbols and other conveniences with Mathjax. As far as I know, I can't easily do it without adapting to Katex-specific syntax.
Everything else on a web page is rendered client side (HTML is just text…) so client side rendering makes sense to me here too.
Rendering HTML doesn't require a huge JS library.
HTML requires a huge browser binary though, and the JS library should be cached on first visit to a page that uses it. Seems the right trade off to me to have a one off download for this use case (i.e. potentially viewing many pages on the same site, as opposed to a small number of pre rendered pages) then only need to transfer plain text which is already in the markdown source (so is needed if you’re going to edit or view the raw MD anyway).
I didn't know that you could also write diagrams, including maps and 3D models: https://docs.github.com/en/get-started/writing-on-github/wor...
Finally a long-awaited feature. Works nicely in dark mode too. However, it simply uses MathJax.
Also there are some minor annoyances. For example you need to escape the backslashes, so it takes 4 backslashes to make a newline in your matrix.
Also there are some minor annoyances. For example you need to escape the backslashes, so it takes 4 backslashes to make a newline in your matrix.
$$\begin{bmatrix} a & b \\\\ c & d\end{bmatrix}$$
In my opinion LaTeX is a poor fit for markdown, although it is the logical—and probably the only—choice. Markdown documents are supposed to be easy to read and quick to type. LaTeX is neither. When I include a matrix in my markdown document I want to type it something like:
Disclaimer, I am an author of an alternative math markup language specifically designed to be a good fit in Markdown.
## Example Matrix
$$$
[a, b; c, d]
$$$
Disclaimer, I am an author of an alternative math markup language specifically designed to be a good fit in Markdown.
I think you're right on all counts, especially on being stuck with LaTeX.
What's your language? Any plans to build some sort of translator or other mechanism to allow high-quality rendering based on it?
What's your language? Any plans to build some sort of translator or other mechanism to allow high-quality rendering based on it?
Thanks for asking... I mentioned it earlier in this thread, and didn’t want to spam it unprompted. But it is called Mathup (https://runarberg.github.io/mathup/) and I purposely just translated to MathML and with the intention to leave rendering to a different library (e.g. MathJax; or the browser if you’re only targeting Firefox or Safari)
I agree. I thought the whole point of markdown was to be simple and readable. At this point, why not just use full latex instead.
the matrix example is a good example of latex being too verbose for its markdown host. \underbrace and \begin{cases} are two others ones that seems antithetical to markdown. and maybe the fact that \left[ and \left( are not the default versions of [ and ( respectively. i'd be interested in collecting more if you can think of them.
I collected some in the doc page for mathup (link in cousin post). Although I’m not sure I tackled \underbrace sufficiently. E.g. This is how I explain up-arrow notion with a mathup expression:
Other improvements include, using white space smartly to group things together e.g. (This example also showcases using slash to denote fraction)
obrace(a\`↑↑`b = ubrace(a^a^⋰^a)._(b "times")).^"" "up-arrow" notation ""
a^n = obrace(a xx a xx cdots xx a).^(n "times")
a^n = (a × a × ⋯ × a).^⏞.^(n "times")
n! = { 1, if n <= 1
(n-1)!, otherwise
Other improvements include, using white space smartly to group things together e.g. (This example also showcases using slash to denote fraction)
a/b + c/d != a / b+c / d> For example you need to escape the backslashes, so it takes 4 backslashes to make a newline in your matrix.
> $$\begin{bmatrix} a & b \\\\ c & d\end{bmatrix}$$
This example doesn't make sense. You need to escape the backslashes in the end-of-row command \\, but you don't need to escape the backslashes in \begin and \end?
The post clearly shows that backslashes in \left, \right, \sum, and \sqrt do not need to be escaped. What's different about \\?
> $$\begin{bmatrix} a & b \\\\ c & d\end{bmatrix}$$
This example doesn't make sense. You need to escape the backslashes in the end-of-row command \\, but you don't need to escape the backslashes in \begin and \end?
The post clearly shows that backslashes in \left, \right, \sum, and \sqrt do not need to be escaped. What's different about \\?
No idea, but if you have only two backslashes instead of four, the matrix would appear as a single row, like [a bc d].
That said, \\begin renders the same as \begin.
That said, \\begin renders the same as \begin.
Oh, this is an experimental result? You've found a bug in Github's parser. You should call it a "bug", not an "annoyance".
This is a pretty aggressive tone. I don't think it's warranted.
As a data point: I have the same experience using MathJax in my own blog (Hugo, Goldmark markdown engine), so I'm assuming there's some structural reason for it, not blaming Github.
As a data point: I have the same experience using MathJax in my own blog (Hugo, Goldmark markdown engine), so I'm assuming there's some structural reason for it, not blaming Github.
Maybe in GitHub Markdown, backslashes have to be escaped only if they could be interpreted as an escape character?
I wonder if, at all, other fonts will ever be used for MathJax max display?
The 'default MathJax font' is also just the 'default LaTeX font' (CM?). There are countless other, high-quality math fonts, for example the TeX Gyre Math fonts. I'd like to see those one day, I prefer them. It would be not more out of place than the current version.
There are font pairs, too, like TeX Gyre Pagella and its TeX Gyre Pagella Math accompanying font. So you have the same font for both, which is simply beautiful and even more readable I'd argue. I think most people have accepted that text and math fonts are always distinct, when in fact they needn't be.
The 'default MathJax font' is also just the 'default LaTeX font' (CM?). There are countless other, high-quality math fonts, for example the TeX Gyre Math fonts. I'd like to see those one day, I prefer them. It would be not more out of place than the current version.
There are font pairs, too, like TeX Gyre Pagella and its TeX Gyre Pagella Math accompanying font. So you have the same font for both, which is simply beautiful and even more readable I'd argue. I think most people have accepted that text and math fonts are always distinct, when in fact they needn't be.
MathJax 3 currently only supports the default font, as more general font support is still under development [1]. According to the relevant GitHub issue, font support is planned to be part of the next major release, which is supposed to arrive sometime this year [2]. This should then include Gyre Pagella out of the box (as was the case for MathJax 2), but also make it possible to use custom fonts (which apparently wasn’t possible with MathJax 2) [3].
[1]: http://docs.mathjax.org/en/latest/output/fonts.html [2]: https://github.com/mathjax/MathJax/issues/2503#issuecomment-... [3]: https://github.com/mathjax/MathJax/issues/2503#issuecomment-...
[1]: http://docs.mathjax.org/en/latest/output/fonts.html [2]: https://github.com/mathjax/MathJax/issues/2503#issuecomment-... [3]: https://github.com/mathjax/MathJax/issues/2503#issuecomment-...
I’m a big fan of Linux Libertine, and I was pleasantly surprised to learn that there is a fork(Libertinus; https://github.com/alerque/libertinus), which includes a math family (Libertinus Math).
They work brilliantly together as well, and in my opinion, a little better fit for the web then TeX Gyre—which is optimized for the printed page.
You can see an example on the doc for my project Mathup: https://runarberg.github.io/mathup/ (you might need firefox or safari to see the font though, as you need the native MathML to render the equations)
They work brilliantly together as well, and in my opinion, a little better fit for the web then TeX Gyre—which is optimized for the printed page.
You can see an example on the doc for my project Mathup: https://runarberg.github.io/mathup/ (you might need firefox or safari to see the font though, as you need the native MathML to render the equations)
Big picture it's interesting how GitHub + Markdown is basically becoming a major content publishing product. Albeit for a technical niche market. Of course I'm not saying this is GitHub's main goal. More like a P1. Instant publishing, diagrams, and now math expressions.
Github becomes a favorite option for research and academic people to work and collaborate their projects their. That is a reasonable move from github to make it more suitable for them. I know my group and several others are relying more and more on github as git host with other products used for collaboration.
Looks like it works with `.org` documents as well! I've been authoring my README files in org-mode for a while now (richer formatting options than Markdown) and GitHub does a great job rendering the org-mode.
I'll have to test AsciiDoc (my markup of choice) when I get a chance. Now, if only GitHub mobile would start rendering my AsciiDoc files, I could use it as my mobile knowledgebase/notes viewer instead of the website version.
I wonder how the grammar works and how this interacts with other Markdown syntax precedence-wise. The specification hasn’t been updated since 2019:
https://github.github.com/gfm/
This clue indicates that it might become really annoying to talk about actual dollar signs in some cases:
https://docs.github.com/en/get-started/writing-on-github/wor...
“Outside a math expression, but on the same line, use span tags around the explicit $.
To split <span>$</span>100 in half, we calculate $100/2$”
https://github.github.com/gfm/
This clue indicates that it might become really annoying to talk about actual dollar signs in some cases:
https://docs.github.com/en/get-started/writing-on-github/wor...
“Outside a math expression, but on the same line, use span tags around the explicit $.
To split <span>$</span>100 in half, we calculate $100/2$”
This is cute but it seems that expressions spanning multiple lines are not rendered
OK:
$$\|\vec{x} - \vec{p}_c\| = v(t_c-t_0)$$
--
NOT OK:
$$
\|\vec{x} - \vec{p}_c\|
= v(t_c-t_0)
$$
This makes larger latex expressions pretty impractical e.g. https://github.com/jurasofish/multilateration/blob/master/re...
OK:
$$\|\vec{x} - \vec{p}_c\| = v(t_c-t_0)$$
--
NOT OK:
$$
\|\vec{x} - \vec{p}_c\|
= v(t_c-t_0)
$$
This makes larger latex expressions pretty impractical e.g. https://github.com/jurasofish/multilateration/blob/master/re...
Complex equations is still broken. Too sad.
e.g., https://github.com/chazeon/notes/blob/master/docs/notes/ml-p...
That first one doesn't compile in LaTeX (assuming \ce is from mhchem?). Perhaps the inline mode $'s shouldn't be in there? i.e.
$$ \ce{ \underset{global coordinate}{(x,y,z)} ->[\mathcal{R}][rotation] \underset{local coordinate}{(x',y',z')} -> \underset{descriptor}{\{\mathcal{D}_{ij}\} } -> E_i } $$
There does appear to be a bug though where the LaTeX expressions don't render if they're in markdown lists or tables.
$$ \ce{ \underset{global coordinate}{(x,y,z)} ->[\mathcal{R}][rotation] \underset{local coordinate}{(x',y',z')} -> \underset{descriptor}{\{\mathcal{D}_{ij}\} } -> E_i } $$
There does appear to be a bug though where the LaTeX expressions don't render if they're in markdown lists or tables.
I wonder if aligned multi line equations would work (I mean eqnarray or aligned environments in latex)
Kind of. See my other note here. The aligned environment work, but there should a curly braces around that are not shown, not sure the cause.
https://github.com/chazeon/notes/blob/master/docs/notes/ml-p...
I would guess that the markdown parser does some overly eager escaping before handing off the input to the latex renderer. If I change the "\left\{" into "\left\\{" and the "\," into "\\," it renders like with LaTeX.
All these TeX-like math syntaxes seem to miss the point of markdown -- that it's as legible as possible in plain text form. I know they're very limited in how much math you can express in plain text, but using backslashes seems to be an admission of defeat.
I'd expect a syntax more like OpenOffice math.
https://wiki.openoffice.org/wiki/Documentation/OOoAuthors_Us...
I'd expect a syntax more like OpenOffice math.
https://wiki.openoffice.org/wiki/Documentation/OOoAuthors_Us...
My one complaint about these new mark down features with github is the lock-in. I’m trying to build a gist compatible service and theres quite a bit to cover. MathJax is fine, but now I (and gitlab, bitbucket, etc) will need to support it
Fyi, GitLab has supported[0] this since quite a while[1].
[0]: https://gitlab.com/gitlab-org/gitlab-foss/-/blob/master/doc/... [1]: https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8...
[0]: https://gitlab.com/gitlab-org/gitlab-foss/-/blob/master/doc/... [1]: https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8...
I really like how GitLab has implemented this. Using code blocks but just with "math" as the language is so much clearer, and avoids having to do awkward dollar sign escaping.
Looking at some of the comments in this thread, I wonder if Hacker News will ever render LaTeX.
I'm having a Baader-Meinhof (frequency illusion) moment, because I was just Googling for equation syntax support in markdown for my Riemann Zeta Function visualization project this past week.
Pluging project here if anyone is interested: https://github.com/atonalfreerider/riemann-zeta-visualizatio...
Pluging project here if anyone is interested: https://github.com/atonalfreerider/riemann-zeta-visualizatio...
Math doesn't render inside a bullet list item. I don't know how to file an issue against Github itself, somewhat ironically.
(I work at GitHub.) We've started using our Discussions product for feedback. You can post a discussion here:
https://github.com/github/feedback/discussions/categories/ge...
https://github.com/github/feedback/discussions/categories/ge...
When we're at it, why isn't GitHub open source?
I feel like being in a bullet list item restricts a lot of the rendering you can do.
It doesn't in HTML/CSS.
This seems complementary to the lean theorem prover, being developed by Microsoft. It's package manager uses github as it's "repository". Having latex in github makes it easy to write mathematical theorems in github readme
Wonderful news!
Unfortunately they don't work on GitHub Pages yet. I still have to resort to GitHub Actions to invoke a container to render my RMarkdowns into a GitHub Pages branch --- wish one day I can retire that pipeline.
Unfortunately they don't work on GitHub Pages yet. I still have to resort to GitHub Actions to invoke a container to render my RMarkdowns into a GitHub Pages branch --- wish one day I can retire that pipeline.
Finally! Gitlab had this feature for so long
Why don’t web browsers just add a tag for mathematical expressions ?
Of course there it is [1], but Chrome doesn't support it and is essentially blocking its adoption. And it is not like MathML is too taxing to browsers; Firefox and Safari had a support for a long time and actually Chrome also once had a support before being dropped due to the instability! [2] The implementation is still underway but is not prioritized enough by Chrome developers.
[1] https://www.w3.org/TR/MathML/
[2] https://caniuse.com/mathml
[1] https://www.w3.org/TR/MathML/
[2] https://caniuse.com/mathml
> **The Cauchy-Schwarz Inequality**
> $$left( \sum_{k=1}^n a_k b_k \right)^2 \leq left( \sum_{k=1}^n a_k^2 \right) left( \sum_{k=1}^n b_k^2 \right)$$
I wonder why their syntax highlighting on this example highlights `left` but not `right`? (I can't seem to reproduce it here, since the HN parser tries to outsmart me.)
> $$left( \sum_{k=1}^n a_k b_k \right)^2 \leq left( \sum_{k=1}^n a_k^2 \right) left( \sum_{k=1}^n b_k^2 \right)$$
I wonder why their syntax highlighting on this example highlights `left` but not `right`? (I can't seem to reproduce it here, since the HN parser tries to outsmart me.)
The reason is that their blog rendering auto-identifies that code block as SCSS and treats “left” as an attribute. Which is strange, since I cannot find something for “left” that is not defined for “right”.
For example, I cannot find a “left” attribute here: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes
For example, I cannot find a “left” attribute here: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes
Some more details. They are using Highlight.js, and `attribute` is what is applied to (S)CSS properties too. But both `left` and `right` are valid properties. What I think is that `\r` is treated as the special Carriage Return character and therefore doesn’t allow `right` to be identified.
KeenWrite, my desktop editor for Markdown and R Markdown documents, provides real-time rendering of TeX equations:
https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
The choice of using TeX over LaTeX is deliberate. Documents written using plain TeX can be rendered by either ConTeXt or LaTeX. I prefer ConTeXt because it makes separating content from presentation easier. One of the benefits of using Markdown, IMO, is to be agnostic as to how the documents are presented. Math could be rendered using ConTeXt, LaTeX, KaTeX, MathJax, JMathTeX, XeTeX, or any other compatible TeX typesetter.
https://wiki.contextgarden.net/Installation
https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
The choice of using TeX over LaTeX is deliberate. Documents written using plain TeX can be rendered by either ConTeXt or LaTeX. I prefer ConTeXt because it makes separating content from presentation easier. One of the benefits of using Markdown, IMO, is to be agnostic as to how the documents are presented. Math could be rendered using ConTeXt, LaTeX, KaTeX, MathJax, JMathTeX, XeTeX, or any other compatible TeX typesetter.
https://wiki.contextgarden.net/Installation
Somewhat tangential but I’ve been enjoying using HackMD for creating nice looking math notes that can be shared with selected folks.
https://hackmd.io/
https://hackmd.io/
[deleted]
[deleted]
Is the renderer working for this page? Both 'renders' seem blurry on 2021 MBP in Chrome.
They’re screenshots.
But why can't they use their render feature for a doc that's literally written in Markdown?
Seems like I can basically make GitHub repo my blogging platform and CMS now, cool!
Finally!
I know, I've been waiting so long for this! I will not miss having to render and reference pngs of equations / api requests.
You think you waited a long time? I wrote a patch to add this to GitHub when I worked there in 2011-12! :) It was rejected at the time by some folks for various “product” reasons, but I’m glad to see it finally become a thing.
Cool, it's 2022
Waiting for this feature for too long! Really good!
Doesn't work on github's builtin wikis
That’s very unfortunate. If anyone from GitHub is here: is that going to be rectified?
Good news!!!
Finally!
Too bad they're not using KaTeX [0] instead.
It renders the maths server-side, so there's no runtime needed.
An additional bonus is that the resulting math is copy-pasteable, which in the case of disply math might not be that useful (since most equations are to complex to be meaningfully copy-pasted with unicode), but it helps from inline math dissappearing when copy pasting texts.
But, that being said, I'm sure they had their reasons to do so. For one, MathJax seems more well-known by quite a bit so maybe it's the safer option.
1: https://katex.org/