Hugo: Better TeX support

[j2kun]

The current Hugo docs provide quite the runaround to get math working for formulas involving underscores. User-contributed alternatives (like custom shortcodes) aren't much better for equation-heavy text. These approaches may be fine for someone starting a new blog, but it is not for me.

I have an existing wordpress.com blog (jeremykun.com), which has hundreds of posts and 5000+ tex equations written over 7 years, which I'd like to convert to hugo. About half of these equations have underscores. I have successfully converted the posts to markdown as it would be used on a site like mathoverflow.com, using standard $ax + b$ and \[x_1 + x_2\] equation fences.

I'm also an engineer, and it's clear that adding regex hacks on top of regex hacks isn't sustainable. If I want to write for another 10 years, chances are good hugo will be replaced with some other engine and I'll have to migrate again.

From what I've gathered, the obstacle is that the markdown rendering engine (Blackfriday) does not support ignoring content in equation fences, and the latex/katex rendering happens after the rendering engine has run. Is that correct? Is there anything else?

If so, I will happily talk to the devs of Blackfriday and add a feature that allows you to configure Blackfriday to ignore markdown characters within specified equation fences. (This seems like it should be trivially easy to me---they already do it for code---but there are always complications I'm sure)

If I did this, would it be possible to incorporate this feature into hugo? I'm imagining a part of the hugo base config.toml that specifies which latex equation fences you'd like to respect (default to none), and hugo simply passes those along to the rendering engine.

[opieters]

I've defined two shortcodes: math.html and inline_math.html resp:

<div class="math">
    {{- .Inner -}}
</div>

<span class="inline_math">{{ .Get 0 }}</span>



md5-369d731c13318940c616a671c5c8c383



fix_html_content = function(html) {
    return html.replace(/&amp;/g, "&").replace(/&gt;/g, ">")
}

window.onload = function() {
    var tex = document.getElementsByClassName("math");
    Array.prototype.forEach.call(tex, function(el) {
        katex.render(fix_html_content(el.innerHTML), el, {displayMode: true});
    });
    var tex_inline = document.getElementsByClassName("inline_math");
    Array.prototype.forEach.call(tex_inline, function(el) {
        katex.render(fix_html_content(el.innerHTML), el);
    });
};

Which corrects all possible issues and renders the LaTeX math code with KaTeX.

I've written it such that it works with all of my code, but it can easily be adapted to work with general LaTeX.

[j2kun]

What I don't like about shortcodes is that they involve too much typing. I often have sentences with 5 equations. An example might be Letting <span class="inline_math">\varepsilon > 0</span>, for any <span class="inline_math">x \in X</span> there is a <span class="inline_math">\delta > 0</span> such that <span class="inline_math">2\delta > \varepsilon + x</span>

I personally can't read with all that noise. What's the point of markdown if you can't read the plaintext?

One option would be to use plain tex fences and have some sort of preprocessor (that hooks into hugo?) that transforms standard tex fences into shortcode fences. But this is also first-party support for tex fences by a different name. It seems like it would be simpler to do the principled solution and fix the markdown engine.

[bwklein]

Have you considered writing your content files in asciidoc and having Hugo build the site by passing your files to asciidoctor to render the HTML?

[j2kun]

@bwklein The problem is that the content is already written. (thousands of pages of text)

I suppose you mean convert the posts from markdown to asciidoc and then have a workflow (somehow built into hugo?) from asciidoc to html. I will look into that, but maybe you could point me to how I would integrate an asciidoc -> html workflow into hugo? Does the hugo CLI do that?

[bwklein]

@j2kun If Hugo sees an AsciiDoc file in the content folder, it will try to run the asciidoctor command on that file by way of 'external helpers'. I need to make a new project with this kind of setup for myself, so I will reply here when I have a demo/tutorial for it. If you can already run asciidoctor from the command line on your PC, it should just work. But, setting up asciidoctor is not always trivial depending on the OS.

[j2kun]

Crickets on https://github.com/russross/blackfriday/issues/504

What a shame. (Perhaps ya'll should be wary about blackfriday becoming a derelict dependency, or fork and incorporate it)

[bwklein]

@j2kun I have a little demo project that I have been playing with.
https://gitlab.com/bwklein/hugo-with-asciidoc-content

This project is using a modified Docker image in GitLab CI/CD to build the site. The image is based on an alpine linux base, and contains an Asciidoctor and Hugo (extended with pipes) installation with the versions controlled in the paramters at the top of the Dockerfile (also in the repo). I am doing it this way to have more control over versions and what asciidoctor extensions that I want available in the build process. This also allows me to run the same docker image locally and not have to mess with installation and setup of the same environment on Windows. I also have firebase tools in the image because I was testing the ability to host the site on Firebase after build. https://tecisitedemo.firebaseapp.com/

Some other bits I am messing with in this project.

• Internationalization of the site and files.
• Using Maid for scripting and various project commands.

[j2kun]

I've used docker before, and my buddy is a Firebase dev :)

I'll take a look, thanks for putting that together!

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[j2kun]

I still think this is valuable, but I have given up hope that it will change. Such a simple fix, too :(