✨ feat: auto-load KaTeX's mchecm extension (#605)

content/blog/markdown/index.ar.md

@@ -1,7 +1,7 @@
 +++
 title = "أمثلة على ماركداون"
 date = 2023-01-31
-updated = 2023-09-01
+updated = 2026-01-01
 description = "تعرض هذه التدوينة بعض الأمثلة على تنسيق ماركداون، بما في ذلك الجداول، والشِفرات البرمجية والوسوم، والاقتباسات، والهوامش."
 
 [taxonomies]
@@ -31,7 +31,7 @@ katex = true
 
 على سبيل المثال، `\\[ r = \frac{\sum_{i=1}^{n}(x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=1}^{n}(x_i - \bar{x})^2}\sqrt{\sum_{i=1}^{n}(y_i - \bar{y})^2}} \\]` سيظهر هكذا: \\[ r = \frac{\sum_{i=1}^{n}(x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=1}^{n}(x_i - \bar{x})^2}\sqrt{\sum_{i=1}^{n}(y_i - \bar{y})^2}} \\]
 
-لتفعيل $\KaTeX$ لتدوينة أو قسم كامل، أضف `katex = true` داخل قسم `[extra]` في المقدمة. على سبيل المثال:
+فعّل $\KaTeX$ بإضافة `katex = true` في `[extra]`:
 
 ```toml,hl_lines=5-6
 title = "تجربة KaTeX"
@@ -41,12 +41,20 @@ date = 2002-11-30
 katex = true
 ```
 
-يمكنك أيضاً تفعيله بشكل عام عن طريق تعيين `katex = true` في قسم `[extra]` في ملف `config.toml` الخاص بك.
+يعمل في: مقدمة الصفحة، `_index.md` للقسم، أو عالمياً في `config.toml`.
 
 لتحسين الأداء والأمان، يتم استضافة ملفات جافا سكريبت و CSS والخطوط الخاصة بـ $\KaTeX$ محلياً.
 
 **ملاحظة**: بعد تفعيل $\KaTeX$، إذا أردت استخدام \$ بدون عرض تعبير رياضي، استخدم شرطة مائلة للخلف قبلها: `\$`.
 
+### الصيغ الكيميائية
+
+الصيغ الكيميائية مدعومة عبر [امتداد mhchem](https://mhchem.github.io/MathJax-mhchem/)، الذي يُحمّل تلقائياً عند استخدام `\ce{}` أو `\pu{}`.
+
+`\ce{}` للكيمياء: $\ce{H2O}$، $\ce{CO2 + H2O -> H2CO3}$
+
+`\pu{}` للوحدات: $\pu{25 °C}$، $\pu{1.2 mol/L}$
+
 ## جدول
 
 هذا مثال على جدول[^1]. تتغير ألوانه حسب سمة التدوينة.

content/blog/markdown/index.ca.md

@@ -1,7 +1,7 @@
 +++
 title = "Exemples de Markdown"
 date = 2023-01-31
-updated = 2025-02-21
+updated = 2026-01-01
 description = "Aquesta publicació mostra alguns exemples de format en Markdown, incloent-hi una taula, blocs de codi i etiquetes, citacions, taules i notes a peu de pàgina."
 
 [taxonomies]
@@ -24,7 +24,7 @@ Per mostrar l'expressió **en una línia pròpia i centrada**, embolcalla-la amb
 
 Per exemple, `\\[ r = \frac{\sum_{i=1}^{n}(x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=1}^{n}(x_i - \bar{x})^2}\sqrt{\sum_{i=1}^{n}(y_i - \bar{y})^2}} \\]` es renderitzarà com: \\[ r = \frac{\sum_{i=1}^{n}(x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=1}^{n}(x_i - \bar{x})^2}\sqrt{\sum_{i=1}^{n}(y_i - \bar{y})^2}} \\]
 
-Per activar $\KaTeX$ en una publicació o secció sencera, inclou `katex = true` dins de la secció `[extra]` de les metadades. Per exemple:
+Activa $\KaTeX$ afegint `katex = true` a `[extra]`:
 
 ```toml,hl_lines=5-6
 title = "Provant KaTeX"
@@ -34,12 +34,20 @@ date = 2002-11-30
 katex = true
 ```
 
-Per activar-lo globalment, afeigeix `katex = true` a la secció `[extra]` del teu `config.toml`.
+Funciona a: metadades de pàgina, `_index.md` de secció, o globalment a `config.toml`.
 
 Per obtenir un millor rendiment i seguretat, els fitxers JavaScript, CSS i les tipografies de $\KaTeX$ s'allotgen localment.
 
 **Nota**: Després d'activar $\KaTeX$, si vols utilitzar el caràcter \$ sense renderitzar-lo com a expressió matemàtica, escapa'l amb una barra inversa: `\$`.
 
+### Fórmules químiques
+
+Les fórmules químiques estan suportades mitjançant l'[extensió mhchem](https://mhchem.github.io/MathJax-mhchem/), que es carrega automàticament en utilitzar `\ce{}` o `\pu{}`.
+
+`\ce{}` per química: $\ce{H2O}$, $\ce{CO2 + H2O -> H2CO3}$
+
+`\pu{}` per unitats: $\pu{25 °C}$, $\pu{1.2 mol/L}$
+
 ## Taula
 
 Aquí tens un exemple de taula[^1]. Els seus colors canvien en funció del tema actual.

content/blog/markdown/index.es.md

@@ -1,7 +1,7 @@
 +++
 title = "Ejemplos de Markdown"
 date = 2023-01-31
-updated = 2025-02-21
+updated = 2026-01-01
 description = "Esta publicación muestra algunos ejemplos de formato Markdown, incluyendo una tabla, bloques de código y etiquetas, citas, tablas y notas al pie de página."
 
 [taxonomies]
@@ -24,7 +24,7 @@ Para mostrar la expresión **en su propia línea y centrada**, envuélvela entre
 
 Por ejemplo, `\\[ r = \frac{\sum_{i=1}^{n}(x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=1}^{n}(x_i - \bar{x})^2}\sqrt{\sum_{i=1}^{n}(y_i - \bar{y})^2}} \\]` se mostraría como: \\[ r = \frac{\sum_{i=1}^{n}(x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=1}^{n}(x_i - \bar{x})^2}\sqrt{\sum_{i=1}^{n}(y_i - \bar{y})^2}} \\]
 
-Para activar $\KaTeX$ en una publicación o sección entera, incluye `katex = true` dentro de la sección `[extra]` del encabezado. Por ejemplo:
+Activa $\KaTeX$ añadiendo `katex = true` en `[extra]`:
 
 ```toml,hl_lines=5-6
 title = "Probando KaTeX"
@@ -34,12 +34,20 @@ date = 2002-11-30
 katex = true
 ```
 
-Para activarlo globalmente, añade `katex = true` en la sección `[extra]` de tu `config.toml`.
+Funciona en: encabezado de página, `_index.md` de sección, o globalmente en `config.toml`.
 
 Para un mejor rendimiento y seguridad, el JavaScript, CSS y las fuentes de $\KaTeX$ se alojan localmente.
 
 **Nota**: Después de habilitar $\KaTeX$, si deseas usar \$ sin representar una expresión matemática, escápalo con una sola barra invertida: `\$`.
 
+### Fórmulas químicas
+
+Las fórmulas químicas están soportadas mediante la [extensión mhchem](https://mhchem.github.io/MathJax-mhchem/), que se carga automáticamente al usar `\ce{}` o `\pu{}`.
+
+`\ce{}` para química: $\ce{H2O}$, $\ce{CO2 + H2O -> H2CO3}$
+
+`\pu{}` para unidades: $\pu{25 °C}$, $\pu{1.2 mol/L}$
+
 ## Tabla
 
 Aquí tienes un ejemplo de una tabla[^1]. Los colores cambian dependiendo del tema actual.

content/blog/markdown/index.md

@@ -1,7 +1,7 @@
 +++
 title = "Markdown examples"
 date = 2023-01-31
-updated = 2025-02-21
+updated = 2026-01-01
 description = "This post showcases some examples of Markdown formatting, including a table, code blocks and tags, quotes, tables, and footnotes."
 
 [taxonomies]
@@ -24,7 +24,7 @@ To display the expression **on its own line and centered**, wrap it around `$$`
 
 For example, `\\[ r = \frac{\sum_{i=1}^{n}(x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=1}^{n}(x_i - \bar{x})^2}\sqrt{\sum_{i=1}^{n}(y_i - \bar{y})^2}} \\]` renders: \\[ r = \frac{\sum_{i=1}^{n}(x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=1}^{n}(x_i - \bar{x})^2}\sqrt{\sum_{i=1}^{n}(y_i - \bar{y})^2}} \\]
 
-To activate $\KaTeX$ for a post or an entire section, include `katex = true` within the `[extra]` section of the front matter. For exemple:
+Enable $\KaTeX$ by setting `katex = true` in `[extra]`:
 
 ```toml,hl_lines=5-6
 title = "Testing KaTeX"
@@ -34,12 +34,20 @@ date = 2002-11-30
 katex = true
 ```
 
-You may enable it globally as well, by setting `katex = true` in the `[extra]` section of your `config.toml`.
+Works in: page front matter, section `_index.md`, or globally in `config.toml`.
 
 For enhanced performance and security, the $\KaTeX$ JavaScript, CSS, and fonts are hosted locally.
 
 **Note**: After enabling $\KaTeX$, if you want to use \$ without rendering a mathematical expression, escape it with a single backslash: `\$`.
 
+### Chemistry formulas
+
+Chemistry formulas are supported via the [mhchem extension](https://mhchem.github.io/MathJax-mhchem/), which loads automatically when using `\ce{}` or `\pu{}`.
+
+`\ce{}` for chemistry: $\ce{H2O}$, $\ce{CO2 + H2O -> H2CO3}$
+
+`\pu{}` for units: $\pu{25 °C}$, $\pu{1.2 mol/L}$
+
 ## Table
 
 Here's an example of a table[^1]. Its colours change depending on the current theme.

scripts/upgrade-deps

@@ -9,8 +9,10 @@ KATEX_CSS_DIR="static"
 KATEX_FONTS_DIR="static/fonts/KaTeX"
 KATEX_JS_FILE="katex.min.js"
 KATEX_CSS_FILE="katex.min.css"
+KATEX_MHCHEM_FILE="mhchem.min.js"
 KATEX_JS_PATH="${KATEX_JS_DIR}/${KATEX_JS_FILE}"
 KATEX_CSS_PATH="${KATEX_CSS_DIR}/${KATEX_CSS_FILE}"
+KATEX_MHCHEM_PATH="${KATEX_JS_DIR}/${KATEX_MHCHEM_FILE}"
 UGLIFY_ITERATIONS=5
 CURL_RETRIES=3
 
@@ -287,7 +289,13 @@ EOM
     local css_comparison_result
     css_comparison_result=$(compare_md5 "${TEMP_DIR}/${KATEX_CSS_FILE}" "${KATEX_CSS_PATH}")
 
-    if [ "$js_comparison_result" = "same" ] && [ "$css_comparison_result" = "same" ]; then
+    # mhchem extension.
+    cp "${TEMP_DIR}/katex/contrib/mhchem.min.js" "${TEMP_DIR}/${KATEX_MHCHEM_FILE}"
+    uglify_file "${TEMP_DIR}/${KATEX_MHCHEM_FILE}" "$UGLIFY_ITERATIONS"
+    local mhchem_comparison_result
+    mhchem_comparison_result=$(compare_md5 "${TEMP_DIR}/${KATEX_MHCHEM_FILE}" "${KATEX_MHCHEM_PATH}")
+
+    if [ "$js_comparison_result" = "same" ] && [ "$css_comparison_result" = "same" ] && [ "$mhchem_comparison_result" = "same" ]; then
         echo "KaTeX: New version is the same as current version. No update needed."
         return 0
     fi
@@ -306,6 +314,12 @@ EOM
         changes_made=true
     fi
 
+    if [ "$mhchem_comparison_result" != "same" ]; then
+        echo "KaTeX mhchem: New version differs from current version. Proceeding with update."
+        mv "${TEMP_DIR}/${KATEX_MHCHEM_FILE}" "${KATEX_MHCHEM_PATH}"
+        changes_made=true
+    fi
+
     rm -rf "${KATEX_FONTS_DIR}"
     mkdir -p "${KATEX_FONTS_DIR}"
     cp -r "${TEMP_DIR}/katex/fonts"/* "${KATEX_FONTS_DIR}/"
@@ -317,7 +331,7 @@ EOM
 
     echo "KaTeX updated successfully!"
     echo "Preparing to commit changes…"
-    git add "${KATEX_JS_PATH}" "${KATEX_CSS_PATH}" "${KATEX_FONTS_DIR}"
+    git add "${KATEX_JS_PATH}" "${KATEX_CSS_PATH}" "${KATEX_MHCHEM_PATH}" "${KATEX_FONTS_DIR}"
     local commit_msg
     commit_msg=$(generate_commit_message "$commit_msg_template" "$latest_version")
     git commit -m "${commit_msg}"

templates/partials/extra_features.html

@@ -46,6 +46,10 @@
 {%- if macros_settings::evaluate_setting_priority(setting="katex", page=page_s, section=section_s, default_global_value=false) == "true" -%}
     <link rel="stylesheet" href="{{ get_url(path='katex.min.css', trailing_slash=false) | safe }}">
     <script defer src="{{ get_url(path='js/katex.min.js', trailing_slash=false) | safe }}"></script>
+    {# Load mhchem extension if chemistry formulas detected #}
+    {%- if page and page.content and ("\ce{" in page.content or "\pu{" in page.content) -%}
+        <script defer src="{{ get_url(path='js/mhchem.min.js', trailing_slash=false) | safe }}"></script>
+    {%- endif -%}
 {%- endif -%}
 
 {# Load mermaid.js #}