Create render hooks for inline and block passthrough snippets #11927

Closed jmooring closed 1 month ago

There is zero demand for this at the moment, but I wanted to describe utility while it's fresh in my head.

layotus/
└── _default/
    └── _markup/
        ├── render-passthrough-block.html
        └── render-passthrough-inline.html

How would these be useful?

Wrap passthrough snippets in an element (e.g., span, figure). In addition to custom presentation, this would provide a targeted way to handle the FOUC exhibited when using MathJax or KaTex.
This would allow you to set a .Page.Store value (e.g., hasMath) to trigger JS inclusion, instead of having to set a site and/or front matter parameter.
It would set us up for server-side rendering in the future (e.g., {{ transform.ToMathML .Inner }}) with something like https://git.sr.ht/~mekyt/latex2mathml (native Go, currently very buggy). Or passing .Inner to a resources.GetRemote call to the free Math API service to embed an SVG.

References:

cc: @j2kun

I'm interested in rendering math server-side! Sounds like implementing these render hooks would pave the road. How can I help?

@Xeyler I'm not aware of any native Go LaTeX-to-MathML or LaTeX-to-SVG tools that are accessible and ready for prime time. https://git.sr.ht/~mekyt/latex2mathml was not even close to ready when I tried it a few months ago. Server-side rendering isn't going to happen unless there's a native Go package (i.e., CGO and Node.js approaches are not acceptable).

What is the reasoning behind only using native Go packages? And (assuming CGO refers to Cairo Go) what makes CGO unacceptable?

About server-side Latex rendering, MathML is supported by "only" 94% of web browsers at the time of this writing. SVG, on the other hand, is supported by more than 98% of web browsers.

Since 2019, MathJax (which is recommended for use in the Hugo docs) hasn't supported MathML output. It does support SVG or CommonHTML output, preferring CommonHTML, which if I understand correctly, is specific to MathJax. CommonHTML is useful because it uses web-based fonts so that users can either load math fonts from a CDN or use a locally-installed font. SVG is potentially useful because the presentation doesn't vary between web browsers.

Now, with respect to Hugo and server-side rendering, the Latex -> MathML or Latex -> SVG tooling isn't quite what it needs to be in Go yet, apparently. latex2mathml is a good start, but it could probably use more unit tests and test-driven development to stabilize the output. Otherwise, a new "latex2svg" go library to convert Latex to SVGs would require more work, but support more web browsers.

Sounds like a lot of work either way, but do I understand the issue and most useful/probable solutions?

CGO = https://pkg.go.dev/cmd/cgo

Our two CGO implementations (libsass and WebP encoding) had a very high development cost; we're not doing that again unless there's no other choice for some critical feature. And server-side LaTeX rendering is not critical.

I outlined the probable solutions in my previous comment.

Our two CGO implementations (libsass and WebP encoding) had a very high development cost;

The development/integration/maintenance cost (significant) is one thing, but but it also makes the build process more complex -- currently we only support the extended (CGO) version of Hugo on Linux, MacOS and Windows.

I understand. It really comes down to a lack of native latex-mathml/svg tooling for Go, then. Maybe I'll investigate latex2mathml and see if there's anything I can do to help development.

Meanwhile, these passthrough render blocks do fall within the scope of Hugo itself. Honestly, I don't have a lot of time right now. I'll have more after the end of the semester in a couple weeks. However, I've used Hugo's render hooks and I'm familiar with how they work. It's been two months since this issue was posted and it looks like it hasn't become anyone else's priority, so I'd like to try my hand at it.

What sort of context would this render hook provide? Something like .PassthroughContent, holding the plaintext content of the block that was "passed through"? What else would be necessary?

it looks like it hasn't become anyone else's priority

It hasn't been accepted either. It's still in the proposal stage, without any demand. I wouldn't spend any time on this right now.

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.

gohugoio / hugo

Create render hooks for inline and block passthrough snippets #11927