mirror of
https://github.com/imfing/hextra.git
synced 2025-06-18 17:43:36 -04:00
feat(math): add optional MathJax support (#707)
* feat: add MathJax option * docs: move math engine note * refactor: update LaTeX documentation and improve MathJax integration - Adjusted LaTeX documentation for clarity and formatting. - Enhanced MathJax configuration in the templates to support both KaTeX and MathJax rendering. - Removed deprecated comments and streamlined the script loading process for MathJax. - Updated the passthrough extension settings in the Hugo configuration for better compatibility with LaTeX math expressions. * docs: simplify LaTeX documentation and clarify configuration steps - Updated LaTeX documentation to reflect that KaTeX is enabled by default, removing the need for manual activation. - Added examples for using LaTeX math expressions and clarified the configuration for the passthrough extension in Hugo. - Enhanced MathJax section to emphasize its use as an alternative rendering engine.
This commit is contained in:
Xin
@ -1,22 +1,10 @@
|
||||
---
|
||||
title: "LaTeX"
|
||||
weight: 4
|
||||
math: true
|
||||
---
|
||||
|
||||
\(\KaTeX\) برای رندر کردن عبارت‌های ریاضی LaTeX استفاده می‌شود. می‌توان آن را در هر صفحه با تنظیم `math` روی `true` در قسمت بالای صفحه فعال کرد.
|
||||
|
||||
<!--more-->
|
||||
|
||||
```yaml {filename="Markdown"}
|
||||
---
|
||||
title: "صفحه من با LaTeX"
|
||||
math: true
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
وقتی فعال باشد، اسکریپت‌ها، شیوه‌نامه‌ها و فونت‌های KaTeX به طور خودکار در سایت شما قرار می‌گیرند. می‌توانید از عبارت‌های ریاضی LaTeX در محتوای مارک‌داون خود استفاده کنید.
|
||||
به طور پیش‌فرض، \(\KaTeX\) برای رندر کردن عبارت‌های ریاضی LaTeX استفاده می‌شود.
|
||||
نیازی به فعال‌سازی دستی نیست، می‌توانید فوراً از عبارت‌های ریاضی LaTeX در محتوای مارک‌داون خود استفاده کنید.
|
||||
|
||||
## مثال
|
||||
|
||||
@ -40,6 +28,46 @@ $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||
|
||||
به عنوان مثال، استفاده از محیط هم‌ترازی:
|
||||
|
||||
```latex {filename="page.md"}
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
```
|
||||
|
||||
به صورت زیر رندر خواهد شد:
|
||||
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
|
||||
## پیکربندی
|
||||
|
||||
> [!IMPORTANT]
|
||||
> لطفاً [افزونه passthrough](https://gohugo.io/content-management/mathematics/) را در فایل پیکربندی Hugo فعال و پیکربندی کنید تا Hugo بتواند عبارت‌های ریاضی LaTeX را در محتوای مارک‌داون شما تشخیص دهد.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ["$$", "$$"]]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
## توابع پشتیبانی شده
|
||||
|
||||
@ -57,4 +85,25 @@ $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
```
|
||||
|
||||
به صورت زیر رندر خواهد شد:
|
||||
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
|
||||
|
||||
## موتور ریاضی
|
||||
|
||||
### MathJax
|
||||
|
||||
به طور پیش‌فرض، [KaTeX][katex] برای رندر کردن عبارت‌های ریاضی LaTeX در طول فرآیند ساخت استفاده می‌شود که روش ترجیحی است.
|
||||
به عنوان جایگزین، می‌توانید از [MathJax][mathjax] برای رندر کردن عبارت‌های ریاضی استفاده کنید.
|
||||
|
||||
برای استفاده از آن، موارد زیر را به فایل پیکربندی `hugo.yaml` اضافه کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: mathjax
|
||||
```
|
||||
|
||||
[katex]: https://katex.org/
|
||||
[mathjax]: https://www.mathjax.org/
|
||||
|
||||
@ -1,22 +1,10 @@
|
||||
---
|
||||
title: "LaTeX"
|
||||
weight: 4
|
||||
math: true
|
||||
---
|
||||
|
||||
\(\KaTeX\) は LaTeX の数式をレンダリングするために使用されます。ページのフロントマターで `math` を `true` に設定することで、ページごとに有効にすることができます。
|
||||
|
||||
<!--more-->
|
||||
|
||||
```yaml {filename="page.md"}
|
||||
---
|
||||
title: "LaTeX を使用した私のページ"
|
||||
math: true
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
有効にすると、KaTeX のスクリプト、スタイルシート、フォントが自動的にサイトに含まれます。Markdown コンテンツ内で LaTeX 数式を使用できます。
|
||||
デフォルトでは、\(\KaTeX\) が LaTeX 数式のレンダリングに使用されます。
|
||||
手動での有効化は不要で、Markdown コンテンツで LaTeX 数式をすぐに使い始めることができます。
|
||||
|
||||
## 例
|
||||
|
||||
@ -40,20 +28,6 @@ $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Hugo 設定ファイルで [パススルー拡張機能](https://gohugo.io/content-management/mathematics/) を有効にして設定してください。これにより、複雑な式のレンダリング問題を回避するために、デリミタ内の生のコンテンツが保持されます。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ['$$', '$$']]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
例えば、aligned 環境を使用する場合:
|
||||
|
||||
```latex {filename="page.md"}
|
||||
@ -78,6 +52,23 @@ $$
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
|
||||
## 設定
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Hugo が Markdown コンテンツ内の LaTeX 数式を検出できるように、Hugo 設定ファイルで [パススルー拡張機能](https://gohugo.io/content-management/mathematics/) を有効にして設定してください。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ["$$", "$$"]]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
## サポートされている関数
|
||||
|
||||
サポートされている関数の一覧については、[KaTeX サポートされている関数](https://katex.org/docs/supported.html) を参照してください。
|
||||
@ -94,4 +85,25 @@ $$
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
```
|
||||
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
次のようにレンダリングされます:
|
||||
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
|
||||
|
||||
## 数式エンジン
|
||||
|
||||
### MathJax
|
||||
|
||||
デフォルトでは、ビルドプロセス中に LaTeX 数式をレンダリングするために [KaTeX][katex] が使用されます（推奨）。
|
||||
代替として、[MathJax][mathjax] を使用して数式をレンダリングすることもできます。
|
||||
|
||||
MathJax を使用するには、`hugo.yaml` 設定ファイルに以下を追加してください:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: mathjax
|
||||
```
|
||||
|
||||
[katex]: https://katex.org/
|
||||
[mathjax]: https://www.mathjax.org/
|
||||
|
||||
@ -1,9 +1,10 @@
|
||||
---
|
||||
title: "LaTeX"
|
||||
weight: 4
|
||||
math: true
|
||||
---
|
||||
\(\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.
|
||||
|
||||
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.
|
||||
|
||||
## Example
|
||||
|
||||
@ -15,7 +16,7 @@ Both inline and separate paragraph LaTeX math expressions are supported in the M
|
||||
This \(\sigma(z) = \frac{1}{1 + e^{-z}}\) is inline.
|
||||
```
|
||||
|
||||
This \(\sigma(z) = \frac{1}{1 + e^{-z}}\) is inline.
|
||||
This \( \sigma(z) = \frac{1}{1 + e^{-z}} \) is inline.
|
||||
|
||||
### Separate Paragraph
|
||||
|
||||
@ -25,21 +26,7 @@ $$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$$
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Please enable and configure the [passthrough extension](https://gohugo.io/content-management/mathematics/) in the Hugo configuration file. It preserves raw content within the delimiters to avoid rendering issues for complex expressions.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ['$$', '$$']]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
$$F(\omega) = \int\_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||
|
||||
For example, using the aligned environment:
|
||||
|
||||
@ -65,6 +52,23 @@ $$
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Please enable and configure the [passthrough extension](https://gohugo.io/content-management/mathematics/) in the Hugo configuration file, so that Hugo can detect LaTeX math expressions in your Markdown content.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ["$$", "$$"]]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
## Supported Functions
|
||||
|
||||
For a list of supported functions, see [KaTeX supported functions](https://katex.org/docs/supported.html).
|
||||
@ -81,4 +85,25 @@ Separate paragraph:
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
```
|
||||
|
||||
will be rendered as:
|
||||
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
|
||||
|
||||
## Math Engine
|
||||
|
||||
### 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:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: mathjax
|
||||
```
|
||||
|
||||
[katex]: https://katex.org/
|
||||
[mathjax]: https://www.mathjax.org/
|
||||
|
||||
@ -4,19 +4,8 @@ weight: 4
|
||||
math: true
|
||||
---
|
||||
|
||||
\(\KaTeX\) 用于渲染 LaTeX 数学表达式。可以通过在页面前置设置中将 `math` 设置为 `true` 来启用它。
|
||||
|
||||
<!--more-->
|
||||
|
||||
```yaml {filename="page.md"}
|
||||
---
|
||||
title: "我的页面包含 LaTeX"
|
||||
math: true
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
启用后，KaTeX 的脚本、样式表和字体将自动包含在您的站点中。您可以在 Markdown 内容中开始使用 LaTeX 数学表达式。
|
||||
默认情况下，\(\KaTeX\) 用于渲染 LaTeX 数学表达式。
|
||||
无需手动激活，您可以直接在 Markdown 内容中开始使用 LaTeX 数学表达式。
|
||||
|
||||
## 示例
|
||||
|
||||
@ -40,20 +29,6 @@ $$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 请在 Hugo 配置文件中启用并配置 [passthrough 扩展](https://gohugo.io/content-management/mathematics/)。它保留分隔符内的原始内容，以避免复杂表达式的渲染问题。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ['$$', '$$']]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
例如，使用对齐环境：
|
||||
|
||||
```latex {filename="page.md"}
|
||||
@ -78,6 +53,23 @@ $$
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
|
||||
## 配置
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 请在 Hugo 配置文件中启用并配置 [passthrough 扩展](https://gohugo.io/content-management/mathematics/)，以便 Hugo 可以检测 Markdown 内容中的 LaTeX 数学表达式。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ["$$", "$$"]]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
## 支持的函数
|
||||
|
||||
有关支持的函数列表，请参阅 [KaTeX 支持的函数](https://katex.org/docs/supported.html)。
|
||||
@ -94,4 +86,25 @@ $$
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
```
|
||||
|
||||
将渲染为：
|
||||
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
|
||||
|
||||
## 数学引擎
|
||||
|
||||
### MathJax
|
||||
|
||||
默认情况下，使用 [KaTeX][katex] 在构建过程中渲染 LaTeX 数学表达式，这是首选方式。
|
||||
或者，您可以使用 [MathJax][mathjax] 来渲染数学表达式。
|
||||
|
||||
要使用 MathJax，请将以下内容添加到 `hugo.yaml` 配置文件中：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: mathjax
|
||||
```
|
||||
|
||||
[katex]: https://katex.org/
|
||||
[mathjax]: https://www.mathjax.org/
|
||||
|
||||
@ -58,7 +58,7 @@ markup:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ["$$", "$$"]]
|
||||
block: [['\[', '\]'], ['$$', '$$']]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
|
||||
|
||||
@ -1,9 +1,20 @@
|
||||
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
|
||||
{{- with try (transform.ToMath .Inner $opts) }}
|
||||
{{- with .Err }}
|
||||
{{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
|
||||
{{- else }}
|
||||
{{- .Value }}
|
||||
{{- $.Page.Store.Set "hasMath" true }}
|
||||
{{- $engine := site.Params.math.engine | default "katex" -}}
|
||||
{{- if eq $engine "katex" -}}
|
||||
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
|
||||
{{- with try (transform.ToMath .Inner $opts) }}
|
||||
{{- with .Err }}
|
||||
{{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
|
||||
{{- else }}
|
||||
{{- .Value }}
|
||||
{{- $.Page.Store.Set "hasMath" true }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- else -}}
|
||||
{{/* MathJax - need to add delimiters back in */}}
|
||||
{{- $.Page.Store.Set "hasMath" true }}
|
||||
{{- if eq .Type "block" -}}
|
||||
\[{{- .Inner -}}\]
|
||||
{{- else -}}
|
||||
\( {{- .Inner -}} \)
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
|
||||
@ -85,7 +85,8 @@
|
||||
|
||||
<!-- KaTeX-->
|
||||
{{ $noop := .WordCount -}}
|
||||
{{ if .Page.Store.Get "hasMath" -}}
|
||||
{{- $engine := site.Params.math.engine | default "katex" -}}
|
||||
{{ if and (.Page.Store.Get "hasMath") (eq $engine "katex") -}}
|
||||
<!-- TODO: make url configurable -->
|
||||
{{ $katexBaseUrl := "https://cdn.jsdelivr.net/npm/katex@latest/dist" }}
|
||||
{{ $katexCssUrl := printf "%s/katex%s.css" $katexBaseUrl (cond hugo.IsProduction ".min" "") -}}
|
||||
@ -103,6 +104,8 @@
|
||||
{{ end -}}
|
||||
{{ end -}}
|
||||
{{ end -}}
|
||||
{{ else if and (.Page.Store.Get "hasMath") (eq $engine "mathjax") -}}
|
||||
{{ partialCached "scripts/mathjax.html" . -}}
|
||||
{{ end -}}
|
||||
|
||||
{{ partial "custom/head-end.html" . -}}
|
||||
|
||||
21
layouts/_partials/scripts/mathjax.html
Normal file
21
layouts/_partials/scripts/mathjax.html
Normal file
@ -0,0 +1,21 @@
|
||||
{{/* MathJax */}}
|
||||
{{ $mathjaxVersion := site.Params.math.mathjaxVersion | default "3" -}}
|
||||
{{ $mathjaxJsUrl := printf "https://cdn.jsdelivr.net/npm/mathjax@%s/es5/tex-chtml.js" $mathjaxVersion -}}
|
||||
<script defer id="MathJax-script" src="{{ $mathjaxJsUrl }}" crossorigin="anonymous" async></script>
|
||||
<script>
|
||||
MathJax = {
|
||||
loader: {
|
||||
load: ["ui/safe"],
|
||||
},
|
||||
tex: {
|
||||
displayMath: [
|
||||
["\\[", "\\]"],
|
||||
["$$", "$$"],
|
||||
],
|
||||
inlineMath: [
|
||||
["\\(", "\\)"],
|
||||
["$", "$"],
|
||||
],
|
||||
},
|
||||
};
|
||||
</script>
|
||||
@ -1,7 +1,7 @@
|
||||
<p class="hx:opacity-50 hx:text-sm hx:leading-7">
|
||||
{{- range $tag := .Params.tags -}}
|
||||
{{- with $.Site.GetPage (printf "/tags/%s" $tag) -}}
|
||||
<a class="hx:inline-block hx:mr-2" href="{{ .RelPermalink }}">#{{ .Title }}</a>
|
||||
{{- range $tag := .Params.tags -}}
|
||||
{{- with $.Site.GetPage (printf "/tags/%s" $tag) -}}
|
||||
<a class="hx:inline-block hx:mr-2" href="{{ .RelPermalink }}">#{{ .Title }}</a>
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
</p>
|
||||
</p>
|
||||
|
||||
Reference in New Issue
Block a user