# Mention Mmark math (MathJax/KaTeX) support in docs #1666

Closed
opened this Issue Dec 3, 2015 · 22 comments

Projects
None yet
7 participants

### oblitum commented Dec 3, 2015

 Duplicating discussion here, since it looks like feasible through Mmark, which has been adopted recently. From Mmark README: Math support, use $$ as the delimiter. If the math is part of a paragraph it will be displayed inline, if the entire paragraph consists out of math it considered display math. No attempt is made to parse what is between the $$. Is this already working? What are the steps to use Mmark and have this enabled? If it's OK for being used, I guess the official hugo docs about MathJax support could be updated with this information. If it's not working, I'd propose for the issue to keep open (in case it's not a "won't fix") to target enabling it for Mmark.
Contributor

### moorereason commented Dec 3, 2015

 Create .mmark files in your content folder instead of .md files. Use the discussion forum to ask questions.

### donbright commented Dec 5, 2015

 Here is my test. I ran the standard setup with hugo_0.15_linux_amd64.tar.gz on ubuntu14 as instructed here http://gohugo.io/overview/quickstart/ I created two files under 'content', about.md and about.mmark The documentation at http://gohugo.io/tutorials/mathjax/ suggests using the following for inline math  blah blah $x^2=y^2$ blah blah  The documentation for "mmark" above suggests using the following for inline math  blah blah $$x^2=y^2$$ blah blah  So I tried them both +++ date = "2015-12-04T22:28:34-06:00" draft = true title = "about.md" +++ Hello $x^2=y^2$ World Hello $$a^2=b^2$$ World
$$x^2 = y^2$$
$$a^2 = b^2$$  +++ date = "2015-12-04T22:28:34-06:00" draft = true title = "about.mmark" +++ Hello $x^2=y^2$ World Hello $$a^2=b^2$$ World
$$x^2 = y^2$$
$$a^2 = b^2$$  Then I edited ../theme/hyde/layouts/partials/head.html as per the official documentation MathJax tutorial at http://gohugo.io/tutorials/mathjax/ (with the recommended javascript and CSS added to the bottom of head section) With the docs solution, it rendered as follows Then i removed the docs javascript solution. It rendered as follows So.. it appears the documented solution for Mathjax might break mmark paragraph math. And also a document written for .mmark format will have paragraph breaks if moved to .md. And it was always orange ( i tried putting the documented .css in many different places, never did figure that part out )

### oblitum commented Dec 5, 2015

 The orange thing is exquisite, but thanks for trying it all through. It looks like Mmark already can be employed just like its documentation says, without the extra javascript and backquotes, which could be added to current gohugo docs.

### JimAmuro commented Jan 2, 2016

 I have found the reason for the orange thing. It is caused by css. See this to solve it. https://groups.google.com/forum/#!topic/mathjax-users/FgCBLdT15nM .

### oblitum commented Jan 2, 2016

 @JimAmuro Thanks for sharing.

### oblitum commented May 27, 2016

 I've been using GitLab Pages hosted Hugo with KaTeX over Mmark to great effect, it works like a charm, no hacks to setup. http://nosubstance.me/post/a-great-toolset-for-static-blogging/

### senykam commented Jun 10, 2016

 Got Hugo working with Mmark and Mathjax. The only issue that came up was with display-mode equations and with references. The problem was the following from the Hugo docs:   This makes Mathjax interpret [...] blocks as display-mode equations whereas Mmark outputs $...$ blocks for display-mode equations. To fix use displayMath: [['$$','$$'], ['\$','\$']] above

Contributor

### rdwatters commented Apr 1, 2017

 New docs take care of this (including the displayMath gotcha): https://hugodocs.info/content-management/formats/#solution

### oblitum commented Apr 1, 2017

 @rdwatters it fails to mention that Mmark is a whole alternative solution to all the hacks and fixes suggested in that page. Mmark simply works. From the modest mention one can think that the MathJax fixes are still necessary when using Mmark while in truth MathJax just works out of the box with it.

### oblitum commented Apr 1, 2017

 I don't consider the "if you're using Mmark" short passage a solution to this issue at all...
Contributor

### rdwatters commented Apr 1, 2017 • edited

 @oblitum it fails to mention that Mmark is a whole alternative solution to all the hacks and fixes suggested in that page Are the Hugo docs intended to extol the virtues of Mmark, which is supported through an external helper, or is that a suggested documentation improvement for...Mmark? This is a legitimate question and not me being snide. I don't know enough about MathJax, which I had to throw into the new formats.md page because it seemed the most fitting after I (rightfully) reworked the entirety of the old "Tutorials" section. That said, I'd certainly appreciate a PR for suggested content revisions if you feel so passionately about it. Seriously: https://github.com/rdwatters/hugo-docs-concept [[EDIT]]: Not through an external helper. Oops.

### oblitum commented Apr 1, 2017 • edited

 @rdwatters that section is a FAQ on MathJax and Mmark is just a dropin solution to many of the issues mentioned there, no need to extol, just mention that it's a solution that happens to be because gohugo ends up using its parser. Notice that I discovered this because I checked sources to know what parsers gohugo was actually using at the time. From the two I've seen I learned that Mmark was a Markdown superset that covered MathJax/KaTeX without need to worry about using divs and other fixes. One should learn that from Mmark parser docs indeed. Duplicating it in GoHugo FAQs is not the intention of the issue but just pointing that Mmark is a supported dialect in GoHugo and that it supports MathJax/KaTeX without issues, and how to activate the Mmark parser.

### oblitum commented Apr 1, 2017

 @rdwatters also, AFAIK, the Mmark parser is built in to gohugo like the default parser, not an external helper that needs an external tool to be installed.

Contributor

### rdwatters commented Apr 1, 2017

 @oblitum Excuse my ignorance on these matters. I re-opened this issue, but you can see the changes I've made to the upcoming docs here: https://hugodocs.info/content-management/formats/#mmark

### oblitum commented Apr 1, 2017

 @rdwatters that's fine but the it solves one of the issues, which is the mention of Mmark support, the other issue is that the section on MathJax has a subsection "Issues with Markdown", issues that don't apply when using Mmark because it covers MathJax already and as such is a natural solution to the "Issues with Markdown" presented there.

### oblitum commented Apr 1, 2017

 @rdwatters relevant docs about that: https://github.com/miekg/mmark/wiki/Syntax#math-blocks. With the parser supporting this, there's no need to worry about the issues mentioned at "Issues with Markdown" and "Solution".
Contributor

### rdwatters commented Apr 1, 2017

 And for users creating content with just markdown/BlackFriday rather than MMark and still using MathJax? Wouldn't they still run into the "Issues with Markdown?"

### oblitum commented Apr 1, 2017

 Yes. Knowing that GoHugo supports a parser builtin where math is a non-issue may be useful information to math interested users.

Contributor

### rdwatters commented Apr 2, 2017

 Thank your for all the feedback @oblitum. At this point, I think this is more than sufficient: https://hugodocs.info/content-management/formats/#issues-with-markdown

Contributor

### rdwatters commented Apr 4, 2017

 @oblitum My pleasure, brother. I appreciate your patience and expertise on this. Hopefully it drives some people to your blog as well 😄 Cheers!

Merged