From 29017f6d82b8212129d3212ffb4ffd354e2bf7a5 Mon Sep 17 00:00:00 2001
From: mtseng15 <tseng.micah@gmail.com>
Date: Mon, 5 May 2025 16:11:38 -0500
Subject: [PATCH] added passthrough

---
 README.md                            | 41 ++++++++++++++++++++++++++++
 layouts/partials/docs/html-head.html |  6 ++++
 layouts/partials/docs/math.html      | 16 +++++++++++
 3 files changed, 63 insertions(+)
 create mode 100644 layouts/partials/docs/math.html

diff --git a/README.md b/README.md
index fa0c304..1c6e8e4 100644
--- a/README.md
+++ b/README.md
@@ -177,6 +177,12 @@ disableKinds = ['taxonomy', 'taxonomyTerm']
   # Can be overwritten by same param in page frontmatter
   BookComments = true
 
+  # (Optional) Enables a Katex math engine that works with the Goldmark markdown 
+  # pass through. This removes the need for shortcodes for math. Also requires 
+  # defining the pass through delimiters. 
+  # See below. 
+  BookKatexMathPassthrough = true
+
   # /!\ This is an experimental feature, might be removed or changed at any time
   # (Optional, experimental, default false) Enables portable links and link checks in markdown pages.
   # Portable links meant to work with text editors and let you write markdown without {{< relref >}} shortcode
@@ -186,6 +192,7 @@ disableKinds = ['taxonomy', 'taxonomyTerm']
   # /!\ This is an experimental feature, might be removed or changed at any time
   # (Optional, experimental, default false) Enables service worker that caches visited pages and resources for offline use.
   BookServiceWorker = true
+
 ```
 
 ### Multi-Language Support
@@ -296,6 +303,40 @@ By default, Goldmark trims unsafe outputs which might prevent some shortcodes fr
 
 If you are using `config.yaml` or `config.json`, consult the [configuration markup](https://gohugo.io/getting-started/configuration-markup/)
 
+## Math
+
+Rendering math equations is enabled by the Katex engine. There are two methods for implementing math support with different benefits. 
+
+### Shortcodes
+
+As described in the Shortcodes section, the Katex shortcode will provide inline and block display (see: [Katex Shortcode](https://hugo-book-demo.netlify.app/docs/shortcodes/katex/)). This method is probably the best if rendering math is only required occasionally. 
+
+### Goldmark Passthrough
+
+Alternatively, the Goldmark markdown rendering engine can be configured to pass blocks defined by delimiters to the Katex engine (see [Hugo docs](https://gohugo.io/content-management/mathematics/#overview)). Thus, short codes are not required. This method is likely the best if rending math is required frequently. 
+
+To enable this feature, add the following to your site configuration. 
+
+```toml
+# Define the delimiters
+[markup]
+  [markup.goldmark]
+    [markup.goldmark.extensions]
+      [markup.goldmark.extensions.passthrough]
+        enable = true
+        [markup.goldmark.extensions.passthrough.delimiters]
+          block = [['\[', '\]'], ['$$', '$$']]
+          inline = [['\(', '\)'], ['$', '$']]
+
+# Enable the pass through rendering
+[params]
+  # ...
+  BookKatexMathPassthrough = true
+  # ...
+```
+
+Note: the delimiters above delimiters are examples only. You can chose your own delimiters. 
+
 ## Versioning
 
 This theme follows a simple incremental versioning. e.g. `v1`, `v2` and so on. There might be breaking changes between versions.
diff --git a/layouts/partials/docs/html-head.html b/layouts/partials/docs/html-head.html
index 6a6d0ec..3f5358a 100644
--- a/layouts/partials/docs/html-head.html
+++ b/layouts/partials/docs/html-head.html
@@ -25,6 +25,7 @@
 <!-- Theme stylesheet, you can customize scss by creating `assets/custom.scss` in your website -->
 {{- $styles := resources.Get "book.scss" | resources.ExecuteAsTemplate "book.scss" . | css.Sass | resources.Minify | resources.Fingerprint }}
 <link rel="stylesheet" href="{{ $styles.RelPermalink }}" {{ template "integrity" $styles }}>
+
 {{- if default true .Site.Params.BookSearch -}}
   {{- $searchJSFile := printf "%s.search.js" .Language.Lang }}
   {{- $searchJS := resources.Get "search.js" | resources.ExecuteAsTemplate $searchJSFile . | resources.Minify | resources.Fingerprint }}
@@ -54,3 +55,8 @@ https://github.com/alex-shpak/hugo-book
     integrity="{{ .Data.Integrity }}" crossorigin="anonymous"
   {{- end -}}
 {{- end -}}
+
+<!--Katex Partial Injection-->
+{{ if .Param "BookKatexMathPassthrough" }}
+    {{ partialCached "docs/math.html" . }}
+{{ end }}
diff --git a/layouts/partials/docs/math.html b/layouts/partials/docs/math.html
new file mode 100644
index 0000000..a3ccf46
--- /dev/null
+++ b/layouts/partials/docs/math.html
@@ -0,0 +1,16 @@
+<!-- Include katex only first time -->
+<link rel="stylesheet" href="{{ "katex/katex.min.css" | relURL }}" />
+<script defer src="{{ "katex/katex.min.js" | relURL }}"></script>
+<script defer src="{{ "katex/auto-render.min.js" | relURL }}" onload="renderMathInElement(document.body, {
+          // customised options
+          // • auto-render specific keys, e.g.:
+          delimiters: [
+              {left: '$$', right: '$$', display: true},
+              {left: '$', right: '$', display: false},
+              {left: '\\(', right: '\\)', display: false},
+              {left: '\\[', right: '\\]', display: true}
+          ],
+          // • rendering keys, e.g.:
+          throwOnError : false
+        });"></script>
+