New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
oblitum opened this Issue Dec 3, 2015 · 22 comments

Comments

Projects
None yet
7 participants
@oblitum

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.

@moorereason

This comment has been minimized.

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

This comment has been minimized.

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

<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

hugowith

Then i removed the docs javascript solution. It rendered as follows

hugowithout

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

This comment has been minimized.

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.

@oblitum oblitum changed the title from Mmark math support (MathJax/KaTeX-with-autorender) to Mention Mmark math (MathJax/KaTeX) support in docs Dec 5, 2015

@JimAmuro

This comment has been minimized.

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

This comment has been minimized.

oblitum commented Jan 2, 2016

@JimAmuro Thanks for sharing.

@oblitum

This comment has been minimized.

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

This comment has been minimized.

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:

<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

@rdwatters

This comment has been minimized.

Contributor

rdwatters commented Apr 1, 2017

New docs take care of this (including the displayMath gotcha):

https://hugodocs.info/content-management/formats/#solution

@rdwatters rdwatters closed this Apr 1, 2017

@oblitum

This comment has been minimized.

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

This comment has been minimized.

oblitum commented Apr 1, 2017

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

@rdwatters

This comment has been minimized.

Contributor

rdwatters commented Apr 1, 2017

@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

This comment has been minimized.

oblitum commented Apr 1, 2017

@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

This comment has been minimized.

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.

@rdwatters rdwatters reopened this Apr 1, 2017

@rdwatters

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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".

@rdwatters

This comment has been minimized.

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

This comment has been minimized.

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.

@oblitum

This comment has been minimized.

oblitum commented Apr 2, 2017

@rdwatters

This comment has been minimized.

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

@rdwatters rdwatters closed this Apr 2, 2017

@oblitum

This comment has been minimized.

oblitum commented Apr 4, 2017

@rdwatters Thanks for all additions.

@rdwatters

This comment has been minimized.

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!

@mtn mtn referenced this issue Dec 15, 2017

Merged

Add latex support #66

3 of 3 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment