transform.ToMath removes html if it contains equations

support
1

Hugo with render-passthrough using transform.ToMath, processes text in markdow <span id="eq-black-scholes">$$\frac{1}{2}$$</span> as it were just $$\frac{1}{2}$$. Have tried both the code from the hugo documentation as well as the answer from a forum post here. To render html, I have also the following in config.toml:

[markup.goldmark.renderer]
  unsafe = true

The format is useful for labelling equations and works perfectly with katex autorender.

2

Please post your entire site configuration, and your render-passthrough.html file.

This works great:

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

We’re updating the transform.ToMath documentation today, and are improving the guidance for how to use it within a passthrough render hook.

3

Hello, you can check the html generated. The displaymode equations do not have the mentioned span id assigned to them.

Here’s a more explicit example, I changed the content in _index.md in your file:

We see the equation here <a href="#eq-black-scholes">Equation 1</a> or the other equation here <a href="#eq-black-scholes1">Equation 2</a>: 

<span id="eq-black-scholes">\[\frac{1}{2}\]</span>

<span id="eq-black-scholes1">$\frac{1}{2}$</span>

Because the equations are on the same page, it’s hard to test if the two links are working but you can zoom into the link in you browser before clicking and the browser adjusts the scroll automatically. This only works for equation 2 and not equation 1 because one is in displaymode and the other not.

4

Sorry about that. The markdown for display mode when you mix HTML and markdown is:

<span id="eq-black-scholes">

$$\frac{1}{2}$$
</span>

The blank line is important. This is sort-of related to the CommonMark spec for mixing HTML blocks with Markdown. Which is complicated.

5

ohhh, wow, thanks a lot. That’s good to know.

1 Like
6

If you want to dig into the complicated rules for mixing HTML and Markdown:

https://spec.commonmark.org/0.31.2/#html-blocks

The most common mistakes are omitting a blank line when closing the HTML block (see notes for block type six), and indenting four or more spaces (makes it an indented code block).

1 Like
7

Sorry to over-communicate on this, but I thought I’d share some draft content from the revised transform.ToMath documentation.

By default, Hugo renders mathematical markup to MathML, and does not require any CSS to display the result.

To optimize rendering quality and accessibility, use the htmlAndMathml output option as described below. This approach requires an external stylesheet.

layouts/_default/_markup/render-passthrough.html

{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with transform.ToMath .Inner $opts }}
  {{- with .Err }}
    {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath template function. The KaTeX display engine threw the following error: %s. See %s." . $.Position }}
  {{- else }}
    {{- . }}
  {{- end }}
{{- end }}
{{- .Page.Store.Set "hasMath" true -}}

Then, in your base template, conditionally include the KaTeX CSS within the head element:

{{ $noop := .WordCount }}
{{ 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 }}

The noop assignment forces Hugo to render the page before we retrieve its Store value. The reason for this is described here.

2 Likes
8

I just looked at the validity of the HTML generated from this Markdown:

<span id="eq-black-scholes">

\[\frac{1}{2}\]
</span>

With the above we’re effectively placing a block element inside of an inline element, which is invalid, and we end up with a stray p element (a block element) within the span (an inline element). For blocks (display mode), wrap them in a div element instead.

<div id="eq-black-scholes">

\[\frac{1}{2}\]
</div>

With that Markdown we don’t render any p elements.

Should we be generating the stray p element? No, which I guess is a bug in the passthrough extension to Goldmark. You’re welcome to log an issue, but I don’t think it will be addressed any time soon given the original Markdown (block within an inline element) doesn’t make sense.

2 Likes
9

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.