Mention Mmark math (MathJax/KaTeX) support in docs
oblitum opened this issue · 23 comments
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.
Create .mmark files in your content folder instead of .md files.
Use the discussion forum to ask questions.
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
<div>$$ x^2 = y^2 $$</div>
$$ 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
<div>$$ x^2 = y^2 $$</div>
$$ 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 )
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.
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 .
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/
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:
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
inlineMath: [['$','$'], ['\\(','\\)']],
displayMath: [['$$','$$'], ['\[','\]']],
processEscapes: true,
processEnvironments: true,
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
TeX: { equationNumbers: { autoNumber: "AMS" },
extensions: ["AMSmath.js", "AMSsymbols.js"] }
}
});
</script>
This makes Mathjax interpret [...] blocks as display-mode equations whereas Mmark outputs \[...\] blocks for display-mode equations.
To fix use displayMath: [['$$','$$'], ['\\[','\\]']] above
New docs take care of this (including the displayMath gotcha):
@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.
I don't consider the "if you're using Mmark" short passage a solution to this issue at all...
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.
@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.
@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.
@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:
@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.
@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".
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?"
Yes.
Knowing that GoHugo supports a parser builtin where math is a non-issue may be useful information to math interested users.
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
@rdwatters Thanks for all additions.
@oblitum My pleasure, brother. I appreciate your patience and expertise on this. Hopefully it drives some people to your blog as well 😄 Cheers!
This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.