From 4d199d757695581a76e99a0b8024ed080c3159f9 Mon Sep 17 00:00:00 2001 From: Etienne Date: Fri, 25 Aug 2023 00:55:29 +0200 Subject: [PATCH] Properly render KaTeX formulas by replacing katex shortcode by katexinline and katexblock --- CHANGELOG.md | 1 + .../content/docs/shortcodes/index.ja.md | 23 +++++++++++------ exampleSite/content/docs/shortcodes/index.md | 25 ++++++++++++------- .../samples/mathematical-notation/index.es.md | 21 ++++++++-------- .../samples/mathematical-notation/index.ja.md | 23 ++++++++--------- .../samples/mathematical-notation/index.md | 21 ++++++++-------- layouts/partials/vendor.html | 2 +- layouts/shortcodes/katex.html | 1 - layouts/shortcodes/katexblock.html | 1 + layouts/shortcodes/katexinline.html | 1 + 10 files changed, 67 insertions(+), 52 deletions(-) delete mode 100644 layouts/shortcodes/katex.html create mode 100644 layouts/shortcodes/katexblock.html create mode 100644 layouts/shortcodes/katexinline.html diff --git a/CHANGELOG.md b/CHANGELOG.md index d20b23dc..a1bb9fd7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - URL to Congo project in footer used deprecated git.io short link ([#605](https://github.com/jpanther/congo/pull/605)) - Various typos in the docs and example site ([#608](https://github.com/jpanther/congo/pull/608), [#609](https://github.com/jpanther/congo/pull/609), [#613](https://github.com/jpanther/congo/pull/613)) +- Properly render KaTeX formulas by replacing `katex` shortcode by `katexinline` and `katexblock`([#633](https://github.com/jpanther/congo/issues/633)) ## [2.6.1] - 2023-06-04 diff --git a/exampleSite/content/docs/shortcodes/index.ja.md b/exampleSite/content/docs/shortcodes/index.ja.md index 6ef62ecf..0a62dde9 100644 --- a/exampleSite/content/docs/shortcodes/index.ja.md +++ b/exampleSite/content/docs/shortcodes/index.ja.md @@ -175,21 +175,28 @@ Congoは、標準的なMarkdown構文を使用した場合の画像について ## Katex -`katex` を使うと、KaTeXパッケージを使って記事の内容に数式を追加することができます。利用可能な構文については[supported TeX functions](https://katex.org/docs/supported.html)のオンラインリファレンスを参照してください。 +数式は `katexblock` (ブロック表現用) または `katexinline` (インライン表現用) ショートコードを使用してレンダリングすることができます。KaTeXライブラリを使用して、記事内の数学表記をレンダリングします。 -記事中に数式を含めるには、コンテンツ内の任意の場所にショートコードを配置するだけです。記事ごとに一度記述するだけで、KaTeXが自動的にそのページのマークアップをレンダリングします。インライン表記とブロック表記の両方がサポートされています。 - -インライン記法は、式を区切り記号 `\\(` と `\\)` で囲むことで生成できます。ブロック記法の場合は `$$` です。 +利用可能な構文については[サポートされているTeX関数](https://katex.org/docs/supported.html)のオンラインリファレンスを参照してください。 **例:** +``` +インライン記法: {{}}f(a,b,c) = (a^2+b^2+c^2)^3{{}} +``` +インライン記法: {{< katexinline >}}f(a,b,c) = (a^2+b^2+c^2)^3{{< /katexinline >}} + +ブロック表記 + ```md -{{}} -\\(f(a,b,c) = (a^2+b^2+c^2)^3\\) +{{}} +f(a,b,c) = (a^2+b^2+c^2)^3 +{{}} ``` -{{< katex >}} -\\(f(a,b,c) = (a^2+b^2+c^2)^3\\) +{{< katexblock>}} +f(a,b,c) = (a^2+b^2+c^2)^3 +{{< /katexblock>}} [数学的表記のサンプル]({{< ref "mathematical-notation" >}})でより多くの例をチェックしてください。 diff --git a/exampleSite/content/docs/shortcodes/index.md b/exampleSite/content/docs/shortcodes/index.md index f3c43fe8..aa0d4cf4 100644 --- a/exampleSite/content/docs/shortcodes/index.md +++ b/exampleSite/content/docs/shortcodes/index.md @@ -175,21 +175,28 @@ Icons can also be used in partials by calling the [icon partial]({{< ref "partia ## Katex -The `katex` shortcode can be used to add mathematical expressions to article content using the KaTeX package. Refer to the online reference of [supported TeX functions](https://katex.org/docs/supported.html) for the available syntax. +Mathematical expressions can be rendered using either the `katexblock` (for block expression) or `katexinline` (for inline expression) shortcode. +It uses the KaTeX library to render mathematical notation within articles. -To include mathematical expressions in an article, simply place the shortcode anywhere with the content. It only needs to be included once per article and KaTeX will automatically render any markup on that page. Both inline and block notation are supported. - -Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters. Alternatively, block notation can be generated using `$$` delimiters. +Refer to the online reference of [supported TeX functions](https://katex.org/docs/supported.html) for the available syntax. **Example:** -```md -{{}} -\\(f(a,b,c) = (a^2+b^2+c^2)^3\\) +``` +Inline notation: {{}}f(a,b,c) = (a^2+b^2+c^2)^3{{}} +``` +Inline notation: {{< katexinline >}}f(a,b,c) = (a^2+b^2+c^2)^3{{< /katexinline >}} + +Block notation: +``` +{{}} +f(a,b,c) = (a^2+b^2+c^2)^3 +{{}} ``` -{{< katex >}} -\\(f(a,b,c) = (a^2+b^2+c^2)^3\\) +{{< katexblock >}} +f(a,b,c) = (a^2+b^2+c^2)^3 +{{< /katexblock >}} Check out the [mathematical notation samples]({{< ref "mathematical-notation" >}}) page for more examples. diff --git a/exampleSite/content/samples/mathematical-notation/index.es.md b/exampleSite/content/samples/mathematical-notation/index.es.md index d9f77b8f..63be80c6 100755 --- a/exampleSite/content/samples/mathematical-notation/index.es.md +++ b/exampleSite/content/samples/mathematical-notation/index.es.md @@ -9,38 +9,39 @@ Una breve muestra de notación matemática en Congo. -{{< katex >}} -Congo solo incluirá los assets de KaTeX en su proyecto si utiliza notación matemática. Para que esto funcione, simplemente incluya el [`katex` shortcode]({{< ref path="docs/shortcodes#katex" lang="en" >}}) dentro del artículo. Cualquier sintaxis de KaTeX en esa página se renderizará automáticamente. +Congo sólo incluirá los recursos de KaTeX en su proyecto si hace uso de la notación matemática. Para que esto funcione, congo proporciona dos shortcodes: [`katexblock` y `katexinline`]({{< ref path="docs/shortcodes#katex" lang="en" >}}). +Cualquier sintaxis KaTeX en esa página dentro de cualquiera de los dos shortcodes se renderizará automáticamente. Utilice la documentación en línea de [funciones TeX admitidas](https://katex.org/docs/supported.html) para conocer la sintaxis disponible. ## Notación en línea -La notación en línea se puede generar envolviendo la expresión en los delimitadores `\\(` y `\\)`. +La notación inline puede generarse envolviendo la expresión en el shortcode `katexinline`. **Ejemplo:** ```tex % KaTeX notación en línea -Notación en línea: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\) +Notación en línea: {{}}\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…{{}} ``` -Notación en línea: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\) +Notación en línea: {{< katexinline >}}\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…{{< /katexinline >}} + ## Notación en bloque -Alternativamente, la notación en bloque se puede generar usando delimitadores `$$`. Esto generará la expresión en su propio bloque HTML. +Alternativamente, puede generarse una notación en bloque utilizando el shortcode `katexblock`. Esto mostrará la expresión en su propio bloque HTML. **Ejemplo:** ```tex % KaTeX notación en bloque -$$ +{{}} \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } -$$ +{{}} ``` -$$ +{{< katexblock >}} \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } -$$ +{{< /katexblock >}} diff --git a/exampleSite/content/samples/mathematical-notation/index.ja.md b/exampleSite/content/samples/mathematical-notation/index.ja.md index c12d1341..558eb2cd 100644 --- a/exampleSite/content/samples/mathematical-notation/index.ja.md +++ b/exampleSite/content/samples/mathematical-notation/index.ja.md @@ -9,38 +9,37 @@ tags: ["sample", "katex", "maths", "shortcodes"] -{{< katex >}} +Congoは、数学的記法を使用する場合にのみ、KaTeXアセットをプロジェクトにバンドルします。これを動作させるために、congoは `katexblock` と `katexinline` という2つのショートコードを提供しています。 +どちらのショートコードでも、そのページのKaTeX構文は自動的にレンダリングされます。 -Congoは、数学的表記を使用する場合にのみ、KaTeXアセットをプロジェクトにバンドルします。これを動作させるには、単に記事内に[`katex` ショートコード]({{< ref "docs/shortcodes#katex" >}})をインクルードしてください。そのページ上のKaTeX構文は自動的にレンダリングされます。 +利用可能な構文については[サポートされているTeX関数](https://katex.org/docs/supported.html)のオンラインリファレンスを参照してください。 -使用可能な構文については、[supported TeX functions](https://katex.org/docs/supported.html)のオンラインリファレンスを参照してください。 ## インライン記法 -インライン記法は、式を `\\(` と `\\)` で囲むことで生成できます。 +インライン記法は `katexinline` ショートコードで式をラップすることで生成できる。 **例:** ```tex % KaTeX inline notation -インライン記法: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\) +インライン記法: {{}}\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…{{}} ``` - -インライン記法: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\) +インライン記法: {{< katexinline >}}\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…{{< /katexinline >}} ## ブロック記法 -あるいは、 `$$` を使ってブロック記法で生成することもできます。これは式を独自のHTMLブロックとして出力します。 +別の方法として、`katexblock`ショートコードを使ってブロック記法を生成することもできます。これは式を独自のHTMLブロックで出力します。 **例:** ```tex % KaTeX block notation -$$ +{{}} \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } -$$ +{{}} ``` -$$ +{{< katexblock >}} \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } -$$ +{{< /katexblock >}} diff --git a/exampleSite/content/samples/mathematical-notation/index.md b/exampleSite/content/samples/mathematical-notation/index.md index 0b184800..8f3f9b4c 100755 --- a/exampleSite/content/samples/mathematical-notation/index.md +++ b/exampleSite/content/samples/mathematical-notation/index.md @@ -9,38 +9,37 @@ KaTeX can be used to render mathematical notation within articles. -{{< katex >}} - -Congo will only bundle the KaTeX assets into your project if you make use of mathematical notation. In order for this to work, simply include the [`katex` shortcode]({{< ref "docs/shortcodes#katex" >}}) within the article. Any KaTeX syntax on that page will then be automatically rendered. +Congo will only bundle the KaTeX assets into your project if you make use of mathematical notation. In order for this to work, congo provides two shortcodes: [`katexblock` and `katexinline`]({{< ref "docs/shortcodes#katex" >}}). +Any KaTeX syntax inside either shortcode will be automatically rendered. Use the online reference of [supported TeX functions](https://katex.org/docs/supported.html) for the available syntax. ## Inline notation -Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters. +Inline notation can be generated by wrapping the expression in the `katexinline` shortcode. **Example:** ```tex % KaTeX inline notation -Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\) +Inline notation: {{}}\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…{{}} ``` -Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\) +Inline notation: {{< katexinline >}}\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…{{< /katexinline >}} ## Block notation -Alternatively, block notation can be generated using `$$` delimiters. This will output the expression in its own HTML block. +Alternatively, block notation can be generated using the `katexblock` shortcode. This will output the expression in its own HTML block. **Example:** ```tex % KaTeX block notation -$$ +{{}} \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } -$$ +{{}} ``` -$$ +{{< katexblock >}} \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } -$$ +{{< /katexblock >}} diff --git a/layouts/partials/vendor.html b/layouts/partials/vendor.html index 3beef0f3..06f67611 100644 --- a/layouts/partials/vendor.html +++ b/layouts/partials/vendor.html @@ -15,7 +15,7 @@ {{ end }} {{/* Katex */}} -{{ if .Page.HasShortcode "katex" }} +{{ if or (.Page.HasShortcode "katexblock") (.Page.HasShortcode "katexinline") }} {{ $katexCSS := resources.Get "lib/katex/katex.min.css" }} {{ $katexCSS := $katexCSS | resources.Fingerprint "sha512" }}