# Issue a warning on equations if those cannot be rendered

**URL:** <https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917>\
**Category:** support\
**Tags:** typesetting\
**Created:** [December 29, 2024, 8:41pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917 "2024-12-29T20:41:49Z")\
**Posts on this page:** 15\
**Page:** 1

<div class="post-metadata">

**Author:** ![wehrend](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/wehrend/32/22842_2.png) [@wehrend](https://discourse.gohugo.io/u/wehrend)\
**Post date:** [December 29, 2024, 8:41pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/1 "2024-12-29T20:41:49Z")

</div>

Hi there,  
I’d like to request a warning if a Katex equaltion or formula cannot be rendered.  
That would be helpful to see in advance.  
Let me know, what you think of that.

---

<div class="post-metadata">

**Author:** ![irkode](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/irkode/32/26135_2.png) [@irkode](https://discourse.gohugo.io/u/irkode)\
**Post date:** [December 29, 2024, 9:20pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/2 "2024-12-29T21:20:40Z")

</div>

#### markdown,

the conversion is usually done at runtime, so you will have to access all pages to check.

with the transform.ToMath (experimental) it’s compile time.

For both options there’s a ThrowOnError to tell KaTex to fail. see docs.

#### asciidoc

have you tried to raise the failurelevel?

> **[Configure markup](https://gohugo.io/configuration/markup/)**
>
> Configure markup.

---

<div class="post-metadata">

**Author:** ![wehrend](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/wehrend/32/22842_2.png) [@wehrend](https://discourse.gohugo.io/u/wehrend)\
**Post date:** [December 30, 2024, 1:24pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/3 "2024-12-30T13:24:11Z")

</div>

Hello irkode,  
thank you for looking into - I tried with --logLevel debug but this gives me only file based granularity, no info about a single equation  
And, yes,l use asciidoc…

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [December 30, 2024, 1:29pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/4 "2024-12-30T13:29:52Z")

</div>

> [@wehrend](#):
>
> And, yes,l use asciidoc…

How are you inserting mathematical markup into your content? Directly? With a shortcode? Please provide an example of your .adoc file.

---

<div class="post-metadata">

**Author:** ![wehrend](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/wehrend/32/22842_2.png) [@wehrend](https://discourse.gohugo.io/u/wehrend)\
**Post date:** [December 30, 2024, 1:47pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/5 "2024-12-30T13:47:10Z")

</div>

Here is an example

```auto
==== Der Ringoszillator
Eine weitere gängige Taktgeberquelle ist der Ringoszillator.
Der Trick besteht darin, eine ungerade Anzahl von Inverter-Gates zu verketten und den Ausgang des letzten Inverters als Eingang
für den ersten Inverter zu verwenden. Auf diese Weise entsteht ein Schwingkreis.

image:../images/how_does_cpu/inverter_chain.svg[width=„400px“]

Die Frequenz hängt von der Anzahl der Inverter sowie von der Laufzeit Tp ab (siehe Gleichung unten). Die Zeit, die das Signal benötigt, um
durch das Gate zu laufen, wird als Laufzeit Tp bezeichnet.

[role=„image“,„../images/how_does_cpu/ring_oscillator_frequency.svg“,imgfmt=„svg“, width=„40%“]
\[f_{ro} = \frac{1}{2nT_{p}}\]

```

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [December 30, 2024, 1:58pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/6 "2024-12-30T13:58:22Z")

</div>

In an AsciiDoc document I would expect to see something like this:

```plaintext
[stem]
++++
f_{ro} = \frac{1}{2nT_{p}}
++++

```

Instead, it looks like you’re relying on katex.js to do the rendering.

Please post:

1. The `[markup.asciidocExt]` section of your site configuration.
2. An example of mathematical markup that cannot be rendered

---

<div class="post-metadata">

**Author:** ![wehrend](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/wehrend/32/22842_2.png) [@wehrend](https://discourse.gohugo.io/u/wehrend)\
**Post date:** [December 30, 2024, 7:08pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/7 "2024-12-30T19:08:44Z")

</div>

My config.toml contains the following:

```auto

[security]
  enableInlineShortcodes = false
  [security.exec]
    allow = ['^dart-sass-embedded$', '^go$', '^npx$', '^postcss$', '^asciidoctor$']
    osEnv = ['(?i)^(PATH|PATHEXT|APPDATA|TMP|TEMP|TERM)$']

[markup.asciidocext]
    extensions = ["asciidoctor"]
    workingFolderCurrent = true
    trace = true
    verbose = true

```

One example that doesnt work is this:

[p \land q = q \land p] |[p \lor q = q \lor p]

Just seeing it now - happy birthday, Joe Mooring

---

<div class="post-metadata">

**Author:** ![irkode](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/irkode/32/26135_2.png) [@irkode](https://discourse.gohugo.io/u/irkode)\
**Post date:** [December 30, 2024, 9:23pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/8 "2024-12-30T21:23:51Z")

</div>

remembering from the past you had a quite special setup regarding hugo and maybe also asciidoctor.

is there anything special as of now regarding Hugo or Asciidoctor apart from the official installation guides.

i’ve seen some gitlab discussions about KaTex rendering in asciidoctor using `\[` and `\]` delimiter - but for me it looks like never merged.

```auto
asciidoctor -version
Asciidoctor 2.0.23 [https://asciidoctor.org]
Runtime Environment (ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [x64-mingw-ucrt]) (lc:IBM437 fs:UTF-8 in:UTF-8 ex:UTF-8)

```

what’s your version?

and as usual a _stripped_ down version of _your_ setup will help. incl just one or two pages with a working and non working equation to replay.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [December 30, 2024, 9:46pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/9 "2024-12-30T21:46:16Z")

</div>

Tested with foo.adoc.

With this in the `head` section of the base template…

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    renderMathInElement(document.body, {
      delimiters: [
        {left: '\\[', right: '\\]', display: true}, // block
        {left: '\\(', right: '\\)', display: false}, // inline
      ],
      throwOnError : false
    });
  });
</script>

```

And this content…

```plaintext
\[[p \land q = q \land p] |[p \lor q = q \lor p]\]

```

I see this:

![image](https://canada1.discourse-cdn.com/flex036/uploads/gohugo/original/3X/2/b/2b1b72029771cf94ffc8d8d66a40d26b60a64acc.png)

Which is exactly how it is rendered on [https://katex.org/](https://katex.org/).

---

<div class="post-metadata">

**Author:** ![irkode](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/irkode/32/26135_2.png) [@irkode](https://discourse.gohugo.io/u/irkode)\
**Post date:** [December 30, 2024, 10:16pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/10 "2024-12-30T22:16:58Z")

</div>

> [@jmooring](#):
>
> `\[[p \land q = q \land p] |[p \lor q = q \lor p]\]`

if I change that to: `\[[p \lan q = q \land p] |[p \lor q = q \lor p]\]`

with the above setup it renders as:

![image](https://canada1.discourse-cdn.com/flex036/uploads/gohugo/original/3X/2/8/287b8bcda34595086ac0d936fba349eb38e6de74.png)

and if I set `throwOnError : true` you’ll see an error in the browser console:

 ![image](https://canada1.discourse-cdn.com/flex036/uploads/gohugo/original/3X/2/c/2c69f7e10646dc4b6b2bc343d79fea9daa8bd90a.png)

which leads to:

> [@jmooring](#):
>
> instead, it looks like you’re relying on katex.js to do the rendering

what about a feature, that the **livereload** catches these error and sends them to the server and that outputs a (supressable?) warning - would at least help all to recon js errors 😉 guess we have to wait for that til next year 😉

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [December 31, 2024, 1:18am UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/11 "2024-12-31T01:18:20Z")

</div>

The error callback opens an alert with the important part of the error stack:

```plaintext
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    renderMathInElement(document.body, {
      delimiters: [
        { left: '\\[', right: '\\]', display: true }, // block
        { left: '$$', right: '$$', display: true }, // block
        { left: '\\(', right: '\\)', display: false }, // inline
      ],
      throwOnError: true,
      errorCallback: (msg, error) => alert(error.stack.split('\n')[0]),
    });
  });
</script>

```

Hugo handles events that occur during the build. JavaScript error handling is somebody else’s problem.

---

<div class="post-metadata">

**Author:** ![wehrend](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/wehrend/32/22842_2.png) [@wehrend](https://discourse.gohugo.io/u/wehrend)\
**Post date:** [December 31, 2024, 11:43am UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/12 "2024-12-31T11:43:58Z")

</div>

Okay, so what do I need to do in the source files – adding the katex.js I suppose.  
Should I add it in the style? Or why is it not existing in the source file?

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [December 31, 2024, 12:29pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/13 "2024-12-31T12:29:27Z")

</div>

> [@wehrend](#):
>
> adding the katex.js I suppose

Are you saying that you were expecting the mathematical markup to be rendered without loading katex.js in the first place???

---

<div class="post-metadata">

**Author:** ![wehrend](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/wehrend/32/22842_2.png) [@wehrend](https://discourse.gohugo.io/u/wehrend)\
**Post date:** [December 31, 2024, 1:01pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/14 "2024-12-31T13:01:13Z")

</div>

No, I thought it (katex.js) would be part of the theme I use, hugo-book and working out-of-the-box.  
But probably I was wrong…

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [December 31, 2024, 1:07pm UTC](https://discourse.gohugo.io/t/issue-a-warning-on-equations-if-those-cannot-be-rendered/52917/15 "2024-12-31T13:07:36Z")

</div>

Why not use the katex shortcode that’s included with the theme?