feat(math): support local katex assets and improve docs (#742)

* refactor(math): update LaTeX guide and enhance KaTeX integration

- Revised the LaTeX documentation for clarity and improved structure, changing section titles and descriptions for better understanding.
- Added support for chemistry expressions using the mhchem extension.
- Introduced a new KaTeX CSS loader partial to streamline the integration of KaTeX, allowing for configurable remote or local asset loading.
- Updated the head partial to utilize the new KaTeX loader, enhancing the flexibility of math rendering options.

* refactor(mathjax): simplify MathJax script URL configuration

- Removed the dynamic version assignment for MathJax and set a fixed version in the script URL for consistency and clarity.

* docs(latex): enhance LaTeX guide and clarify chemistry expressions

- Updated section titles for better clarity, changing "Supported Functions" to "Chemistry Expressions."
- Improved description of the mhchem extension for rendering chemistry equations.
- Removed redundant instructions regarding the passthrough extension in Hugo.
- Corrected minor typographical errors in references to MathJax.

exampleSite/content/docs/guide/latex.md

@@ -3,32 +3,35 @@ title: "LaTeX"
 weight: 4
 ---
 
-By default, \(\KaTeX\) is used for rendering LaTeX math expressions.
-No manual activation is needed, you can start using LaTeX math expressions in your Markdown content right away.
+LaTeX math expressions are rendered using \(\KaTeX\) by default. Simply start including them in your Markdown content without any manual configurations.
 
-## Example
+## Usage
 
-Both inline and separate paragraph LaTeX math expressions are supported in the Markdown content.
+You can use LaTeX for both inline expressions and for larger blocks of text.
 
-### Inline
+### Inline Math
+
+To include an expression within a line of text, wrap it in `\(` and `\)` delimiters.
 
 ```markdown {filename="page.md"}
-This \(\sigma(z) = \frac{1}{1 + e^{-z}}\) is inline.
+This \(\sigma(z) = \frac{1}{1 + e^{-z}}\) is an inline expression.
 ```
 
-This \( \sigma(z) = \frac{1}{1 + e^{-z}} \) is inline.
+This \( \sigma(z) = \frac{1}{1 + e^{-z}} \) is an inline expression.
 
-### Separate Paragraph
+### Display Math
+
+For expressions that you want to stand on their own in a separate paragraph, use `$$` delimiters.
 
 ```markdown {filename="page.md"}
-$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
+$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
 ```
 
 will be rendered as:
 
-$$F(\omega) = \int\_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
+$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
 
-For example, using the aligned environment:
+You can also use LaTeX environments like `aligned` for multi-line expressions.
 
 ```latex {filename="page.md"}
 $$
@@ -52,6 +55,23 @@ $$
 \end{aligned}
 $$
 
+For a list of supported functions, see [KaTeX supported functions](https://katex.org/docs/supported.html).
+
+### Chemistry Expressions
+
+The [mhchem][mhchem] extension is enabled by default, allowing you to easily render chemistry equations and formulas.
+
+Inline: \(\ce{H2O}\) is water.
+
+Separate paragraph:
+
+```markdown {filename="page.md"}
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+```
+
+will be rendered as:
+
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
 
 ## Configuration
 
@@ -69,35 +89,47 @@ markup:
         enable: true
 ```
 
-## Supported Functions
+### Math Engine
 
-For a list of supported functions, see [KaTeX supported functions](https://katex.org/docs/supported.html).
+[KaTeX][katex] is the default engine used to render LaTeX math expressions during the build process supported by [Hugo][hugo-transform-tomath].
 
-## Chemistry
+The default is KaTeX, but you can also switch to [MathJax][mathjax] if you need features only available in MathJax.
 
-Chemistry expressions are supported via [mhchem](https://mhchem.github.io/MathJax-mhchem/) extension.
+#### KaTeX
 
-Inline: \(\ce{H2O}\) is water.
+The default setup requires no configuration. Hugo fetches the KaTeX CSS from the CDN.
+If you need to pin a specific version of KaTeX or use local assets, you can do so in your `hugo.yaml` file.
 
-Separate paragraph:
+##### Override CDN base URL
 
-```markdown {filename="page.md"}
-$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+```yaml {filename="hugo.yaml"}
+params:
+  math:
+    engine: katex
+    katex:
+      base: "https://cdn.jsdelivr.net/npm/katex@0.16.22/dist"
 ```
 
-will be rendered as:
+##### Use local assets
 
-$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+You can also place the css file under `assets` and publish additional font files required by KaTeX.
 
+```yaml {filename="hugo.yaml"}
+params:
+  math:
+    engine: katex
+    katex:
+      css: "css/katex.min.css"
+      assets:
+        - "fonts/KaTeX_Main-Regular.woff2"
+        # Add other font files here
+```
 
-## Math Engine
+It will load the KaTeX CSS file from `assets/css/katex.min.css` instead of downloading from CDN.
 
-### MathJax
+#### MathJax
 
-By default, [KaTeX][katex] is used for rendering LaTeX math expressions during the build process, which is preferred.
-Alternatively, you can use [MathJax][mathjax] to render math expressions.
-
-To use it instead, add the following to the configuration `hugo.yaml` file:
+Alternatively, you can use [MathJax][mathjax] to render math expressions:
 
 ```yaml {filename="hugo.yaml"}
 params:
@@ -105,5 +137,10 @@ params:
     engine: mathjax
 ```
 
+> [!NOTE]
+> You can further customize MathJax (for example, adjust loader options, or change the CDN/source) by overriding the template at `layouts/_partials/scripts/mathjax.html` in your project. Hugo will use your version instead of the theme's default.
+
 [katex]: https://katex.org/
 [mathjax]: https://www.mathjax.org/
+[mhchem]: https://mhchem.github.io/MathJax-mhchem/
+[hugo-transform-tomath]: https://gohugo.io/functions/transform/tomath/