Support for server-side math rendering with MathJax/KaTeX

[shreevatsa]

This is a feature request, and apologies that it is a half-baked one: I'm throwing up an idea before investigating it carefully.

Background:

• To get properly typeset mathematics on a web page, the usual options are MathJax/KaTeX.

• In their more commonly used client-side rendering mode, they are used as a piece of JavaScript on the page that scans the DOM for math fragments and replaces them with typeset HTML+CSS (or SVG, or…).

• Hugo can take care of including this JS on the page, but the main problem using MathJax/KaTeX with Hugo is making sure that one's math markup in the input source file (.md) makes it through to the final generated HTML unscathed (so that MathJax/KaTeX have the correct syntax to work on).

• ox-hugo helps here, as it allows the user to write natural LaTeX syntax, and recognizes math blocks on the page and carefully escapes them before exporting to MarkDown, so that after Hugo works on it, the correct syntax will be left on the generated HTML page.

• MathJax and KaTeX also have (less commonly used) support for server-side rendering, where the JavaScript code can be run (using Node.js I think) by the page author, so that the HTML+CSS (or SVG…) can be generated and put into the rendered HTML directly. That way, the user's browser doesn't need to run JavaScript (and wait for it to finish) to display the typeset mathematics.

Now my question is about whether ox-hugo, currently the best (and only?) way to easily insert mathematics into Hugo-generated sites, could be made to support this server-side rendering. The advantage for the reader would be as mentioned above: the page would load faster (no waiting for the mathematics to get typeset), and even without JavaScript being enabled.

This would probably require invoking js from ox-hugo during export (if node is installed on the user's computer). So I don't know how feasible / out-of-scope it is, sorry for not checking. But it might be something worth looking into. (Unrelated but Pandoc can do this, via a filter that handles the math elements…)

[kaushalmodi]

This would probably require invoking js from ox-hugo during export

I am not familiar with JS or nodejs. But I believe that you can do something like this to call any elisp function (that would be calling your script) once the exporting is done.

So I don't know how feasible / out-of-scope it is, sorry for not checking.

It's out of scope of ox-hugo because it uses the ox.el machinery to export different elements like headings, bold, italics, code blocks, etc. You can uses advices or wrap the ox-hugo export function in another function where it also runs the nodejs scripts.

[shreevatsa]

Thanks for the reply!

Calling a script after exporting the HTML is an interesting idea, but I don't know how reliable it will be to parse the HTML file to identify the math elements... As ox-hugo is able to identify the math elements (whatever is inside $…$ or \(…\) or $$…$$ or \[…\] according to this page) I was rather thinking of a hook/advice that we can call during its exporting to markdown, that can operate directly on the elements identified by ox-hugo as math elements. That is, for all the other elements (headings, italics, code blocks etc) ox-hugo would do its standard thing, but specifically for math elements instead of its usual thing (exporting properly escaped syntax to Markdown), it would call a script and export something else instead. Does this make sense / is it possible? I briefly looked up ox.el and it seems to contain options like org-export-with-latex and org-export-filter-latex-fragment-functions so maybe it's possible to do something custom just for them, but I haven't understood the code carefully enough to know...

[kaushalmodi]

@shreevatsa Yes, you can tweak just the selected functions. See this.

Relevant part:

The Org export process has many filter sets applicable to different types of objects, plain text, parse trees, export options, and final output formats. The filters are named after the element type or object type: org-export-filter-TYPE-functions, where TYPE is the type targeted by the filter. Valid types are ..

You might want to add filter functions to org-export-filter-latex-environment-functions and org-export-filter-latex-fragment-functions.

---

but I haven't understood the code carefully enough to know

The my-latex-filter-nobreaks example in the Org Manual link in this comment should help you.

[kaushalmodi]

Closing this issue as I am assuming this to be resolved. Feel free to comment further in this thread.

[shreevatsa]

Finally gave this a try, over a year later. Thanks for your advice and suggestions!

Leaving a note here of what I did, just in case it's useful to anyone else finding this issue, or someone can make it less hacky.

I put something like the following in .emacs, which puts the text into a tmpfile and calls an external shell command:

(defun my-latex-filter-common (display-mode text backend info)
  "text will be something like '\\(1 + \\frac12 + \\frac13 + \\dots\\)' and backend will be 'hugo'."
  (when (string= backend "hugo")
    (let* ((tmpfile (make-temp-file "use-katex" nil "katex-input" text))
	   (result (shell-command-to-string (format "NODE_PATH=/usr/local/lib/node_modules /usr/local/bin/node /Users/shreevatsa/Downloads/use-katex.js %s < %s" (if display-mode "display" "inline") tmpfile))))
      (message "Using tmpfile %s" tmpfile)
      ;; (string-trim result)
      result
      )))

(defun my-latex-filter-inline (text backend info)  (my-latex-filter-common nil text backend info))
(defun my-latex-filter-display (text backend info)  (my-latex-filter-common t text backend info))
(add-to-list 'org-export-filter-latex-fragment-functions 'my-latex-filter-inline)
(add-to-list 'org-export-filter-latex-environment-functions 'my-latex-filter-display)

Here, use-katex.js is the following file:

const katex = require('katex');

const fs = require("fs");
let input = fs.readFileSync(0).toString(); // Read from stdin

let displayMode = process.argv[2] == 'display' ? true : false;
if (input.startsWith(String.raw`\\(`)) displayMode = false;
else if (input.startsWith(String.raw`\\[`)) displayMode = true;
else console.log('to display or not to display?');

// The start and end of the string
input = input.replace(String.raw`\\(`, '').replace(String.raw`\\)`, '');
input = input.replace(String.raw`\\[`, '').replace(String.raw`\\]`, '');
// undscores are escaped -- unescape them
input = input.replaceAll(String.raw`\_`, '_');
// \, gets escaped into \\, -- revert this
input = input.replaceAll(String.raw`\\,`, String.raw`\,`);

var html = katex.renderToString(input, {
    throwOnError: false,
    displayMode: displayMode,
});

console.log(html);

Results and problems:

• This worked for one particular post I tried just now, but I haven't tried anything more nontrivial with pmatrix and whatnot.

• For something like \(n\)th, this inserts a space after the n — this can be got rid of with string-trim as in the commented-out code above, but it removes the space everywhere else (even in \(n\) th, say).

• I think the hacks to detect inline-versus-display mode on the Emacs side may probably not be needed, but the biggest problem is all the hacks in the js code to revert the escaping that has already happened on the Org/Ox end. Ideally we'd get the raw text string before the escaping happens.
  I tried setting the org-export-with-latex to verbatim, but then our filter functions don't even get called. From what I understand of the comments in ox.el, I think the "transcoders", which I guess are org-blackfriday-latex-environment and org-blackfriday-latex-fragment, must themselves be replaced. Maybe this can be done with advice and :override or something, but I haven't tried it yet.

[kaushalmodi]

From what I understand of the comments in ox.el, I think the "transcoders", which I guess are org-blackfriday-latex-environment and org-blackfriday-latex-fragment, must themselves be replaced. Maybe this can be done with advice and :override or something, but I haven't tried it yet.

That's exactly right! If you just override those 2 functions, you won't need any hack to unescape the complicated escaping that ox-hugo otherwise does for Hugo.

---

Thanks for sharing your solution here. I have converted this issue to a discussion for more visibility for other KaTeX users looking for server side rendering.