37

I want to add some explanation to an example. I would like to add a mathematical formula to that explanation. Sure, the code executes that formula, but it's often obscured by the syntax of the language.

What's the best way to do that?

MathJax is not supported on Documentation as it seems. It would be great to have that option.

I could use external tools to create the formula and then include it as an image. The problem with that is that it's impossible to edit the formula later.

4
  • I haven't played around on Documentation to know if this would work, but a trick I've seen for Code Snippets is to include a script tag pointing to the MathJax CDN.
    – Teepeemm
    Jul 27, 2016 at 21:05
  • Like in the beginning of this question
    – Teepeemm
    Jul 27, 2016 at 21:08
  • 1
    @Teepeemm as of now, snippets are not available on documentation.
    – null
    Jul 27, 2016 at 21:16
  • 2
    @Teepeemm To add to what null said, I would say adding unrelated code snippets to an example just to format a math equation would be inappropriate. Examples shouldn't be full of unrelated code/distractions.
    – Kendra
    Jul 27, 2016 at 21:49

1 Answer 1

4

It has been discussed in the Meta that the performance hit of MathJax outweighs its merits, on SO. While this is perhaps less critical for Documentation, I suppose it's still enough of an issue that MathJax isn't going to happen here.

IMO that's ok – while I also like to underpin stuff with proper maths formulas, it probably is ill-advised to do that on SO if it involves stuff too complex to express in unicode / html. Which is actually not that little – I summarised some possibilities here.

If that's not enough and you really need something more graphical... well, you can still always just include an image of a formula, though it should clearly be a last resort.

3
  • 10
    The SO meta discussion was a bit flawed due to bad timing (beta testing, new DNS etc. see dpvc's comments on that thread). It would also be easy to create a more optimized inline script that checks for math markup before loading MathJax. Jul 28, 2016 at 7:20
  • 1
    "you can still always just include an image of a formula, though it should clearly be a last resort." -1 That's a very good way to make a post difficult to maintain. I shouldn't have to reverse-engineer the formula, dig up a TeX compiler use, and a screenshot tool, in order to change the formula if needed for content improvements. Users behind some corporate firewalls may be able to load the site but not from *.imgur.com (including i.stack.imgur.com). If the client-side performance hit of mathjax is too much, then rendering can/should be moved to the server-side (like how Wikimedia does it).
    – nanofarad
    Jul 28, 2016 at 12:00
  • @hexafraction the used mathjax could be added in a comment next to the image. Your argument of reduced maintainability is actually more valid for any other image, because the creation process is entirely unknown. Despite that and the possible blocking off them, images are still allowed, because they can be superior to text when it comes to explaining stuff. Server side rendering is a great idea that would solve all of that.
    – null
    Jul 28, 2016 at 12:14

Not the answer you're looking for? Browse other questions tagged .