How to use the transform.ToMath function?

[Spew]

Hello, hope that question from non-technical folks is tolerated here. I am trying to eliminate the use of JS on a simple website I have setup using Hugo and followed steps in this hugo documention to use transform.ToMath however, the equations are not rendered. I am using hugo v0.133.0
Here’s the config.toml:

[markup]
  [markup.goldmark]
    # Allow rendering of raw HTML
    [markup.goldmark.renderer]
      unsafe = true
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true
        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['\[', '\]'], ['$$', '$$']]
          inline = [['\(', '\)'], ['$', '$']]
    [markup.goldmark.parser]
      [markup.goldmark.parser.attribute]
        block = true

and for layouts/_default/_markup/render-passthrough.html I have added the same from the documentation:

{{ if eq .Type "block" }}
  {{ $opts := dict "displayMode" true }}
  {{ transform.ToMath .Inner $opts }}
{{ else }}
  {{ transform.ToMath .Inner }}
{{ end }}

For full context, I’ve used $$\frac 1 2$$, $\frac 1 2$, \(\frac 1 2\) and \[\frac 1 2\] in the markdown file for testing.

[deining]

@Spew

Hello, hope that question from non-technical folks is tolerated here.

Yes, of course.

@Spew

For full context, …

Sorry, but that’s not the full context.
Please show the full site/code you are using. Ideally, you create a repo that shows your current approach. Then share this repo with us, e.g. on GitHub or so. This way, we can effectively help you and hopefully solve your problems within short time. Thanks for providing us with your minimal repo!

[davidsneighbour]

Did you follow these steps too? To actually render equations you need to load a JS file on those pages. After you got MathML of any kind running with the steps in THIS documentation then you can try to change the passthrough renderer.

[irkode]

@Spew

the equations are not rendered

especially here I miss some details. Isn’t it that you get the following error:

Error: error building site: render: failed to render pages:
 render of "home" failed: "C:\_repos\github\clone\topic-52152\layouts\_default\home.html:3:6":
  execute of template failed: template: _default/home.html:3:6: executing "main" at <.Content>:
   error calling Content: "C:\_repos\github\clone\topic-52152\content\_index.md:1:1":
    execute of template failed: template: _default/_markup/render-passthrough.html:1:0:
     executing "_default/_markup/render-passthrough.html" at <_html_template_htmlescaper>:
      error calling _html_template_htmlescaper: not a function

Keep in mind, that the toMath is marked as “experimental”

looks like this is called if the displayMode option is set:

• this does fails when .Type is “block”

  {{ if eq .Type "block" }}
    {{ $opts := dict "displayMode" true }}
    {{ transform.ToMath .Inner $opts }}
  {{ else }}
    {{ transform.ToMath .Inner }}
  {{ end }}
  

• If you omit these $opt it seems to work for both block and inline

  The hook becomes just:

  {{ transform.ToMath .Inner }}
  

and then this is rendered properly:

Markdown equations

inline: $ c = \pm\sqrt{a^2 + b^2} $ is fine

block:

$$ c = \pm\sqrt{a^2 + b^2} $$

Yours also work

$$\frac 1 2$$, $\frac 1 2$, \(\frac 1 2\) and \[\frac 1 2\]

ScreenShot

dunno if this is a documentation or also an implementation issue or something else

Maybe also if this is as it is according to: transform.ToMath, WASI/Wasm modules feedback thread · Issue #12736 · gohugoio/hugo · GitHub

@jmooring , @bep

[bep]

@irkode

Keep in mind, that the toMath is marked as “experimental”

Which does not mean that it’s not working nor that it’s going away (it’s just allowing me to have a slightly better conscience I need to change the API slightly).

I think hhe mystic “calling _html_template_htmlescaper: not a function” error is masking the “real error” (I know what happens there and we/I should fix the error handling/reporting).

That said, if you found a bug, please create a GitHub issue and I will look at it, but we have pretty good tests for this feature.

[jmooring]

@Spew Take this for a spin:

git clone --single-branch -b hugo-forum-topic-52152 https://github.com/jmooring/hugo-testing hugo-forum-topic-52152
cd hugo-forum-topic-52152
hugo server

Files of interest:

• hugo.toml
• layouts/_default/_markup/render-passthrough.html
• layouts/_default/baseof.html (lines 8-12)

@davidsneighbour The transform.ToMath template function does not require any JavaScript. The transformation is performed during the build, not on the client side.

If you set the “output” option to html or htmlAndMathml, you need to include the KaTeX CSS file. That’s what we do in the example site above.

Using html or htmlAndMathml output looks better than mathml. I recommend using htmlAndMathml for accessibility.

hugo.toml

[markup.goldmark.extensions.passthrough]
enable = true
[markup.goldmark.extensions.passthrough.delimiters]
block = [['\[', '\]'], ['$$', '$$']]
inline = [['\(', '\)'], ['$', '$']]

layouts/_default/_markup/render-passthrough.html

{{ $opts := dict "output" "htmlAndMathml" }}
{{ if eq .Type "block" }}
  {{ $opts = merge $opts (dict "displayMode" true) }}
{{ end }}
{{ transform.ToMath .Inner $opts }}
{{ .Page.Store.Set "hasMath" true }}

layouts/_default/baseof.html

...
<head>
  ...
  {{/* https://gohugo.io/troubleshooting/faq/#why-is-my-page-scratch-or-store-missing-a-value */}}
  {{ $noop := .Content }}
  {{ if .Store.Get "hasMath" }}
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
  {{ end }}
  ...
</head>
...

[irkode]

mmh, I just started to produce a minimal reproducible example … and failed

adapted witzh your minimal settings, I’m unable to get that fail again - will investigate the difference with the previous setup.

git clone --single-branch -b topic-52152 https://github.com/irkode/hugo-forum.git --depth 1 topic-52152
cd topic-52152
hugo server

hugo.toml

baseURL = 'https://example.org/'
title = 'Topic-52152'

disableKinds = ['sitemap', 'rss', 'taxonomy', 'term']

[markup.goldmark.extensions.passthrough]
   enable = true
[markup.goldmark.extensions.passthrough.delimiters]
   block = [['\[', '\]'], ['$$', '$$']]
   inline = [['\(', '\)'], ['$', '$']]

layouts/home.html

<!doctype html>
<html lang="en">
   <body>
      {{ .Content }}
   </body>
</html>

layouts/_default/_markup/render-passthrough.html

{{ $opts := dict "displayMode" (eq .Type "block") }}
{{ transform.ToMath .Inner $opts }}

_index.md

title = 'transform.toMath'

date = 2023-01-01T08:00:00-07:00

draft = false

+++

## Markdown Equations

inline: $ c = \pm\sqrt{a^2 + b^2} $ is fine

block:

$$ c = \pm\sqrt{a^2 + b^2} $$

These also work

$$\frac 1 2$$, $\frac 1 2$, \(\frac 1 2\) and \[\frac 1 2\]

[Spew]

Hello ^^
WOW, that’s amazing, it works out of the box for me!
I’ll be comparing codes from my site and your example trying to figure out where I messed up, and I’ll comment about it here once I figure out. Thanks a lot for the files.

@irkode Sorry, I can only guess that it has something to do with you hugo version maybe. I’m using hugo v0.133.0 windows/amd64. Also I tried omitting options like you mentioned but I’m getting same results.

[jmooring]

@irkode

error calling _html_template_htmlescaper

You can trigger this error by erroneously double-escaping something within block delimiters, for example:

\[\\frac 1 2\]

You may have done something similar.

https://github.com/gohugoio/hugo/issues/12990

[irkode]

that’s exactly what I just detected.

in the example from toMath Basic

{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}

I just copied it to the markdown file and it produces the error but only for block mode which sets “displayMode” true.

With the inline mode where no options are set it produces p m s q r t

<mi>p</mi><mi>m</mi><mspace linebreak="newline"></mspace><mi>s</mi><mi>q</mi><mi>r</mi><mi>t</mi><mrow><msup><mi>a</mi><mn>2</mn></msup><mo>+</mo><msup><mi>b</mi><mn>2<

So no error there, but the result is not correct

as always - you’re toooooo fast for me - thx for help with the analysis and follow up actions.

[irkode]

I checked with 0.133.0 and the error is the same - so guess you have something inside your equation that breaks it

your example code from above works fine with the same symptoms

• block errors out
• inline renders the frac litteraly

[jmooring]

To be clear, all of these work as expected without errors:

{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}

{{ transform.ToMath `c = \pm\sqrt{a^2 + b^2}` }}

{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" (dict "displayMode" true) }}

{{ transform.ToMath `c = \pm\sqrt{a^2 + b^2}` (dict "displayMode" true) }}

[Spew]

@irkode seems like latex syntax unsupported by pandoc is also able to cause that same error. For example, \^Z should be equivalent to \hat Z but is unsupported by pandoc. Just putting this out here in case it helps.

PS I got everything working and eventually figured that the code provided in the documentation also works, it seems that I had spelled a few more things wrong so, my bad. Let’s hope that this thread remains useful to someone anyway. Especially nice to compare a working example