begin equation in $$

Kolen's Avatar


23 Feb, 2016 08:03 AM


I was testing the use of Math in mmd, and found that if I use $$\begin{equation}\nabla \times \mathbf{E} = - \frac{\partial \mathbf{B}}{\partial t}\end{equation}$$ in the md file, the tex generated will becomes this: $\begin{equation}\nabla \times \mathbf{E} = - \frac{\partial \mathbf{B}}{\partial t}\end{equation}, which leads to error. I tested other combinations and they are fine.

I case you need the file I used, it is attached.

  1. Support Staff 1 Posted by fletcher on 23 Feb, 2016 02:39 PM

    fletcher's Avatar

    To make sure I have the correct solution, the problem is the presence of the '$' at the beginning of the output you list, correct?

    If so, the problem was a typo in the latex.c file -- it started output at character offset 1 instead of offset 2 (which caused the inclusion of the second '$').

    If you verify I have the correct solution, I'll push a fix to the development branch on github. It will be included in the next version of MMD as well.



  2. Support Staff 2 Posted by fletcher on 23 Feb, 2016 02:42 PM

    fletcher's Avatar

    PS -- do you mind if I use your examples in my test suite?


  3. 3 Posted by Kolen on 28 Feb, 2016 01:39 AM

    Kolen's Avatar

    Yes, you are correct. And no, I don't mind you using any of those in the test suite.

    And sorry for replying so late. It was partly because of a busy week, and because of some deeper issue I am digging into. In short, it is related to how LaTeX environments like \begin{equation}... should be used in MMD, MathJax, pandoc, etc. And I found that in MathJax, mmd, pandoc, they all didn't really specify clearly on how LaTeX environments should be used. I opened a repository in ickc/mathjax-latex-md-mmd-pandoc: Testing LaTeX Environments Usage in MathJax From Markdown Convertion (including mmd and pandoc), which basically have a couples of test files, and documented the problems there.

    LaTeX Environments in MMD

    In summary,

    • MathJax actually expects LaTeX environments to be by itself, but not in a math delimiter (i.e. \begin{... is the correct way). But, probably due to how mathjax.js process it, it is not as strict as LaTeX and there is no error code nor erroneous output if \(begin{... or \[\begin... is used (i.e. the output will looks identical to when \begin{... is used instead).
    • In the way I understand it (according to the test files over there), mmd expects \\(begin{... or \\[\begin... and in HTML output it becomes \(begin{... or \[\begin..., in LaTeX it becomes begin{....
      • The problem is, some environment like the \beign{aligned}... are expected to be in an environment (e.g. \[\beign{aligned}...), so that way mmd would output \[\beign{aligned}... in HTML (correct), but \beign{aligned}... in LaTeX (incorrect). I have mentioned a temporary workaround that works with the current MMD in the link above.

    Improvement and Compatibility

    I am not sure how the problem should be addressed though. First, I think the documentation could be improved by documenting how MMD expects LaTeX environments to be used.

    In terms of "bugs fix", I think the correct way to use the environment is the way MathJax supposed to use (which is identical to LaTeX's usage). i.e. any \begin... seen in Markdown should be recognized as math elements and not touched. But this leads to a backward compatibility issue in mmd, and also I am not sure how much more complicated it will becomes if \begin{...}...\end{...} needed to be parsed as a math elements as well. (alternatively may be it should be untouched, like the example file on vanilla markdown in the repository above.)

    But the backward compatibility would be very complicated. For example,

    1. we want \\[\begin{equation} works in HTML (either \[\begin{equation} or \begin{equation} is fine) and works in LaTeX (\begin{equation}).
    2. But for \\[\beign{aligned}..., we definitely need \[\beign{aligned}... in both HTML and LaTeX.

    In the MWE.html and MWE.tex in the repository, you can see the usage of all environments MathJax supported. From there you can see which environments are supposed to be in delimiter or not.

    As a sidenote, amscd is required when the CD environment is used. So may be in mmd-load-ams in the LaTeX support documents, you could add amscd there as well.

    Another Small Issue Related To $

    From the test files, I found that MMD process the delimiter in this way:

    MMD Source HTML Output LaTeX Output
    $...$ \(...\) $...$
    $$...$$ \[...\] $$...$$
    \\(...\\) \(...\) $...$
    \\[...\\] \[...\] \[...\]

    [Current MMD]

    I liked the freedom MMD provided that both TeX and LaTeX styled math delimiters are support (rather than like pandoc, it forces you to make a choice in the whole document). But I think that the HTML output is the correct way, where the LaTeX output is not. Because the dollar sign delimiter is said to cause some problem the the AMS packages. I suggest MMD to change the LaTeX output in the same way the HTML is doing:

    MMD Source HTML Output LaTeX Output
    $...$ \(...\) \(...\)
    $$...$$ \[...\] \[...\]
    \\(...\\) \(...\) \(...\)
    \\[...\\] \[...\] \[...\]

    [Proposed MMD]

    You might say $$...$$ can be avoided if \\[...\\] is used. But I think because in Markdown, one more \ is required to escape it, it makes the math delimiter \\(...\\) and \\[...\\] cumbersome in Markdown. So might be $...$ and $$...$$ are better ways to write in Markdown, while \(...\) and \[...\] should be the correct output in both HTML and LaTeX for maximal compatibility.

  4. Support Staff 4 Posted by fletcher on 01 Mar, 2016 09:58 PM

    fletcher's Avatar

    To be honest, this is too detailed for me to really have a strong
    opinion about, given:

    1. I have not had significant feedback re: MMD and math in a long time
    (outside of minor bug reports that were obvious).

    2. Lots of people use MMD and math, but I am not getting lots of complaints.

    3. I use some math, but not much. What I do works just fine.

    If you feel something should be changed (outside of something that is
    broken), I recommend bringing it up to the discussion list to get input
    from other MMD users. If there's a consensus, I can definitely consider it.


  5. 5 Posted by Kolen on 02 Mar, 2016 12:58 AM

    Kolen's Avatar

    I am sorry I didn't have written it clearer. In short, the problem is a lack of spec and documentation. MathJax, mmd, and pandoc all didn't document how environments (and things related to LaTeX) should be used. I opened an issue in MathJax Doc in MathJax Documentation Is Ambiguous on How Environments Should Be Used · Issue #146 · mathjax/MathJax-docs, and they say that it is related to historical issue too, since in the past a math delimiter is required to be around begin{.... And in the newer releases, they gives many options in tex2jax. i.e. MathJax has multiple ways of doing the same thing, and none of the ways are either documented (in the page talking about environment) or recommended.

    It isn't a problem that MathJax didn't have a "spec"—a recommended way of writing the LaTeX code—since it gives configurable options.

    But for mmd (and pandoc), there's no way to configure how the math is rendered. We can setup MathJax in HTML in mmd, but not how mmd will interpret if a section is math or not, and how it will transform it.

    The shortest example is this:


    Both will works in MMD2HTML generations (because MathJax is lenient on what it reads) but the MMD2TEX generation will results in an error in the align environment.

    The correct way to write it in MMD is this:


    That's my finding in the test files in the repository mentioned above.

    While I wish these would be different, for backward compatibility's sake I am not asking to change how this should behaves. But I believe a "spec" should be given in the documentation, meaning that in the doc one should be able to find the "correct way" to write such codes in mmd, as the example shown above.

    If I have time I might add a M!WE-mmd in the repository to show exactly the seemingly correct way to write a wrong code in mmd (similar to the example above).

    And please take a look at the section "Another Small Issue Related To $" above. it is a different issue and doesn't involve such complication as backward compatibility. I would say my suggestion actually will improve compatibility. (because $$ can case errors in amsmath package and generally discouraged in LaTeX)

  6. 6 Posted by Kolen on 02 Mar, 2016 01:04 AM

    Kolen's Avatar

    I will add that I am willing to help expanding the doc about the recommended method of writing math equations, although I don't know the inner working of mmd I am not sure what I say will be correct. (e.g. how /ref, /def should be used. I could write more tests to see how mmd is tranforming them but that is like a blackbox and trying to figure out what mmd expects...)

  7. Support Staff 7 Posted by fletcher on 02 Mar, 2016 02:24 AM

    fletcher's Avatar

    MMD Math starts with \\[, \\(, $, or $$. It ends with the appropriate
    matching string.

    MMD doesn't interpret LaTeX, except that if the math starts with
    "\begin" and we're exporting to LaTeX, we trim off the MMD delimiters
    from above.

    If one is having trouble with LaTeX, you can skip MMD's math feature
    altogether and use HTML comments:

    <!-- This is raw \LaTeX -->


  8. Kolen closed this discussion on 02 Mar, 2016 02:50 AM.

  9. Kolen re-opened this discussion on 02 Mar, 2016 10:17 AM

  10. 8 Posted by Kolen on 02 Mar, 2016 10:17 AM

    Kolen's Avatar

    What I said is that there is a way to write environments in MMD such that both HTML and LaTeX generations would be valid. It is better than raw LaTeX. It only needs to be documented.

    And for someone like me I always want to have both options in the output. I don't want to worry about the output format when I input and there is a way to do it as far as environments is concerned. One only need to find the right way, like what my tests up there did.

    I don't understand how those smart people figured it out and knows the right way to do it all the time, as no one has mentioned it so far. But for stupid people like me, it took me more than a year to realize this subtlety, and spent quite some time to write tests to see what it expects me to do.

    And I did read the documentation, mmd's documentation is one of the very few that I would constantly refer back to, and read through more than once, but the information on the matter just wasn't there. Even as simple as what you just said (about the trimming), would be helpful.

    Edit: the example I given before is wrong! I was referring to aligned. Correction:


    Both will works in MMD2HTML generations (because MathJax is lenient on what it reads) but the MMD2TEX generation will results in an error in the aligned environment.

    The correct way to write it in MMD is this:


    Since the \\[ and \begin{aligned} are separated, it is not trimmed out and so the LaTeX output is correct.

  11. Kolen closed this discussion on 02 Mar, 2016 10:17 AM.

  12. fletcher re-opened this discussion on 30 Oct, 2016 01:08 AM

  13. Support Staff 9 Posted by fletcher on 30 Oct, 2016 01:08 AM

    fletcher's Avatar

    I just pushed a commit to the develop branch that no longer outputs $-delimited math in LaTeX, using \[ or \( instead.

    Let me know if it works the way you think it should -- I'll push it to the master branch this week.


  14. fletcher closed this discussion on 02 May, 2018 12:18 AM.

Comments are currently closed for this discussion. You can start a new one.

Keyboard shortcuts


? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac

Recent Discussions

30 May, 2020 05:22 PM
03 Mar, 2020 06:14 PM
20 Dec, 2019 11:26 PM
25 Oct, 2019 08:22 PM
30 Aug, 2019 03:59 PM

Recent Articles