Mathematics extension

I’m sure that this wouldn’t be to popular for the diehard mathematicians, as they all swear by using LaTeX, which can be converted to HTML by MathJax.

That’s probably similar to that there will always be people that swear by using HTML even if they have the option to use Markdown. But for people that just sometimes want to use a little bit of mathematics in their markdown chat/discussion/article/blogpost etc. having a mathematics extension to markdown could be quite useful.

I’m thinking about things like:

Probably not a priority at this moment, but I just want to drop the idea. Peter Jipsen wrote such a kind of markdown alternative to LaTeX already 10 years ago, for the people interested:

But I think this is already too feature rich. I would rather have only the very basic mathematics in such a markdown extension, and leave the heavy work to mathjax.

1 Like

How would you recognize lines as mathematics, without getting things like > confused for html characters etc… ( I think most implementation tries to parse in a ‘context’ free kind of way )

I’d agree with putting anything like this as an extension, not in the core, because it may conflict with those that want to use mathjax/other math formatting solutions.

But what about adding in dollar signs in the core similar to how pandoc handles it:

Anything between two $ characters will be treated as TeX math. The opening $ must have a character immediately to its right, while the closing $ must have a character immediately to its left. Thus, $20,000 and $30,000 won’t parse as math. If for some reason you need to enclose text in literal $ characters, backslash-escape them and they won’t be treated as math delimiters.

And then have the math itself remain untouched (so that the website/system can format it however they want with mathjax or with something else) but wrapped with a <span> tag with class math?

Similarly, two dollar signs ($$) could be used as block equation/math delimeters (similar to ``` for code blocks and single backticks for inline code), and then be wrapped with a <div> tag with class math?

And of course the mathjax itself should be left for websites/systems themselves do deal with; however they want to implement it. (This is the only way since mathjax inherently needs the concept of a browser, a dom, so stmd shouldn’t try to automatically include mathjax on math equations itself, since the output doesn’t make sense by itself.)

This way, it’s easier to clearly mark such text as equations. If that’s too conflicting with regular text (math equations aren’t really a core feature that everyone would use), perhaps it could be an extension too?

Edit: I’m recommending this syntax because it’s already widely used in places where latex code is used and in latex itself, so it makes copy/pasting easier. And in general would mean less friction with everything else, as opposed to simply manually doing div/span tags classed as math.

converting things into ‘math’ should be an extension. But simply ‘indicating’ that something is maths could be allowed for (e.g. marking that section as maths for mathjax to convert), would be smart.

Btw do you mean this? $1+1=2$? Well what if someone wants to type some currency terms e.g. $32

But the block idea doesn’t sound too bad, it reminds me of code blocks.

\frac{1,2} = 0.5

Though I would wonder why can’t we use something like code fencing to deal with this. E.g.

\frac{1,2} = 0.5

edit: to keep inline with code fence spec .latex --> latex

1 Like

I agree, that’s what I meant.

Read the quote from pandoc from my previous comment. :wink:

The difference between two dollar signs for math and simply labelling it as ‘latex’ code is that the dollar signs indicate that we want something like mathjax to process this as math and display it better (like how mathjax converts it to how you would actually write it with a pen). But if it’s latex code, we don’t want that, we just want to label it as code and display the characters/code as is, usually with a monospace font, because it’s the code itself we are interested in, not the equation/math. (Maybe also syntax highlight it, which is common with code.)

I think we are talking about different things here.

I was talking about a much simplified, not latex related math support for markdown. Just for very simple math formulas, for the more difficult math formulas, we have MathJax.

The other thing is, having support for MathJax. Which is way more imporant, than my silly proposal. Not that MathJax should be included out of the box, but it would be great if it is possible to add MathJax to any CommonMark editor, just by adding the MathJax script to the website. To let this work, anything between $…$, $$…$$, \(…\), \[…\] should be ignored by CommonMark.

1 Like

I know, sorry for hijacking the thread/being somewhat off topic. I should have used the “reply as new Topic” option I think.

That would be very awesome. I agree that the parser should ignore MathJax inline maths in:

$...$, $$...$$, \(...\), \[...\]

Currently using normal markdown + mathjax leads to this cumbersome workaround:

\$...\$, \$\$...\$\$, \\(...\\), \\[...\\]

This is already clearly annoying me in other programs that tries to implement both markdown and mathjax.


In No-markdown islands I just thought about how this could be an extension.

    latex: $ ... $
    C: /* ... */ 

$ 1+1 = 2 $
/* hello world */

This above is local to the page only, but I’m sure it could be possible to create a sitewide header for declaring these as needed.

Just thought of another nifty extension, evaluable maths

if this is displayed maths

$ 1+1 = 2 $

Recall: general directive syntax ![](){} (shorthand for !default[](){} )

Then what about using this syntax !$ ... $ or !eval$ ... $ or if that is too confusing for the parser then try !eval[ $ ... $ ] ( Recall $ for inline and $$ for block in latex)

!eval$ 1+1 = $

!!!eval latex
 1+1 =
 1+2 = 3
 2+3 =

evals in a pretty way to:

1+1 = 2

1+1 = 2
1+2 = 3 (verified)
2+3 = 5

Note that IPython already implements this feature in the IPython notebook’s flavor of Markdown: $…$ is converted into an equation via MathJax.

(In the Julia language, we are considering using Markdown for docstring-like documentation, and we are planning to imitate IPython’s $…$ equation syntax. Since Julia is aimed at technical computing, equations in documentation are essential.)


this got me thinking that we should provide support for consistent ways to implement inline code snippet evaluations via !eval[](){}, not just for latex commands. Maybe it could process python snippets as well.


!eval{ language=python }
!eval`print( "hello world)`

```!eval python
  print( "hello world)

Imagine being able to run multiple styles of codes on the same page. E.g. a section in matlab, a section in python, with latex mathematical proofs evaluated that is self tested. etc…


I think math is important enough to deserve a special $…$ syntax. I agree with rwzy that Pandoc’s syntax is common enough, and has proved itself so usable in practice (e.g. in IPython notebooks), that it is worth recognizing as the de facto standard.

(Note that IPython and Pandoc also support $$…$$ for block equations.)

I don’t think that all conformant Markdown implementations should be expected to support LaTeX equation rendering, but as a fallback they should leave $…$ and $$…$$ blocks alone (or perhaps render them as code).


The $…$ looks intersting, but I believe it needs to be refined to avoid ambiguities. In the following sentence

This diamond is worth sometwhere between 500$ and 700$

you would have an inline math expression and 700. To prevent this, the $…$ could be turned into a block level expression. E.g. we could say something like the first $ has to be the first character of the line, followed by two spaces and the line ends with two spaces followed by a $. E.g.

$  1 + 2 = 3  $

I believe in this example, the $ signes would not be too disturbing while reading the plain text to get closer to what @Kasper was asking for in the first place.

I personally don’t like the $ sign, because it is already used for so many things in non mathematical context. For money, for variable names etc. Therefore, I would prefer using code fencing like

2pi**-1 = 1 / (2 x 3.14) = 0.16

But with this example, we are getting further away from what @Kasper originally asked. There would be too much stuff around each equation, if you put explanations between each equation. Tricky…

What about using a different symbol combination, that is attracting less attention on itself and is less used than the $ sign E.g two dashes and one space:

-- 2pi**-1 = 1 / (2 x 3.14) = 0.16 --

Open for more ideas…

No, this would not create an equation in the pandoc syntax, because the first $ does not have a non-space character immediately to its right. Similarly for the more-standard format “$500 and $700”.

If you mean sites that simply process through a markdown->html converter, then run mathjax on the resulting page, the problem with that is not just cumbersome syntax but bugs where markdown interprets charcters inside the math, notably _ or *:

$A*B + C*D$
-> $A<em>B + C</em>D$
$\\vec{x}_y$ is coprime to $a_{b,c}$
-> $\vec{x}<em>y$ is coprime to $a</em>{b,c}$

which confuses or completely breaks the math rendering, and leaves blocks of text randomly italicized.

Thinking through double processing is not something that should ever be inflicted on users…

The only healthy thing to do is for markdown parser to preserve and mark math blocks (e.g. <span class="math">) and disable mathjax processing outside of them.

1 Like

Hi! I’m a Phd student in math. I’m interest in the concept of Open Notebook Science, and I have tested tools that support markdown+MathJax.

I think that the possibility of math support in commonMark specification, still that as a extension, is essential for mathematical community.

The markup syntax (markdown+iTeX2MML) implemented in instiki wiki project, seems me very good. I suggest a look .

1 Like

The markup syntax (makdown+iTeX2MML) implemented in instiki wiki project, seems me very good. I suggest a look .

As noted above, the problem with that syntax is that \[ and \( already have clearly defined meanings: they are escaped [ and ( characters, and it is very important that there be a way to escape these characters in certain circumstances.

But I’m certainly in agreement about the importance of supporting math.


Hi, I’d just like to point out that the discussion here about not parsing contents surrounded by some kind of special delimiter has a strong connection with an earlier thread in no-markdown islands.

I guess this is an opportunity to tackle a better and simpler solution than have the spec addressing math specifically. Even though my main usecase for opening that thread is my experience using LaTeX/MathJax with several parsers, I see it as not fundamental regarding the problem of literal data inside CommonMark content.

One single and short approach to this in the spec could solve anything related to supporting MathJax, LaTeX mixed with CommonMark, or other kind of literal data that must end up as-is in the output after the parsing phase, not mattering whether it compiles to HTML, LaTeX or other thing.

This is not an area that I am familiar with, but at least for blocks of math I don’t see why fenced code blocks couldn’t be used:

2^2=2*2 = 4

1/2 + 1/2 = 1


(a + b = c) => (a = c-b)

The presentation of the block could be handled by CSS and/or another parser designed specifically for displaying math. Essentially, math would be treated as just another type of code.

Inline math is more difficult if you want to style it a particular way; there is a similar problem for inline programming code.