KaTeX 構文を利用できるようにする (#27)

* cspellにkatexを追加

* marked-katex-extensionを追加

* marked-katex-extensionをmd-to-pdf設定に追加し、スタイルシートとスクリプトを更新

* 数式をドキュメントテンプレートに追加し、KaTeXの使用方法を説明

* pdf-sample.mdに数式のレンダリングサンプル追加

cspell.json

@@ -14,6 +14,7 @@
     ],
     "words": [
         "drawio",
+        "katex",
         "markdownlint",
         "stylesheet",
         "textlint",

docs/_document-template/contents.md

@@ -47,6 +47,7 @@ dest: ./output/ドキュメントテンプレート.pdf
     - [2.15. 水平線](#215-水平線)
     - [2.16. エスケープ](#216-エスケープ)
     - [2.17. アラート](#217-アラート)
+    - [2.18. 数式](#218-数式)
 - [3. 参考資料](#3-参考資料)
 
 # 1. ドキュメントの全体設定
@@ -565,6 +566,43 @@ tip の内容。
 warning の内容。
 !!!
 
+## 2.18. 数式
+
+[KaTeX](https://katex.org/) で数式を記述できます。
+インラインに数式を入力する場合は、 `$` で囲った中に、 KaTeX の構文を記述してください。
+`$` の前後にスペースを 1 つ以上入れてください。
+
+```md
+インラインに数式を $c = \pm\sqrt{a^2 + b^2}$ のように記述できます。
+```
+
+これは次のようにレンダリングされます。
+
+インラインに数式を $c = \pm\sqrt{a^2 + b^2}$ のように記述できます。
+
+`$$` で囲うと、ブロック要素として KaTeX の構文を記載できます。
+`$$` の前後に空行を設けてください。
+
+```md
+$$
+\begin{cases}
+   &10x &+ &3y  &= &2 \\
+   &3x  &+ &13y &= &4
+\end{cases}
+$$
+```
+
+これは次のようにレンダリングされます。
+
+$$
+\begin{cases}
+   &10x &+ &3y  &= &2 \\
+   &3x  &+ &13y &= &4
+\end{cases}
+$$
+
+ブロック要素とした場合、数式は中央寄せで配置されます。
+
 # 3. 参考資料
 
 詳細な構文については、以下をご覧ください。

md-to-pdf-config.js

@@ -1,4 +1,9 @@
 const admonition = require('marked-admonition-extension');
+const markedKatex = require('marked-katex-extension');
+
+const markedKatexOptions = {
+    throwOnError: false
+  };
 
 const mermaid_renderer = {
     code(code, infoString) {
@@ -10,10 +15,13 @@ const mermaid_renderer = {
 };
 
 module.exports = {
-	stylesheet: ["https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.7.0/github-markdown.min.css",
-        "docs/base-style.css"],
+	stylesheet: [
+        "https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.7.0/github-markdown.min.css",
+        "https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css",
+        "docs/base-style.css"
+    ],
 	body_class: 'markdown-body',
-    marked_extensions: [ admonition.default ],
+    marked_extensions: [ admonition.default, markedKatex(markedKatexOptions) ],
 	marked_options: [{ mermaid_renderer }],
 	pdf_options: {
 		format: 'a4',
@@ -24,7 +32,9 @@ module.exports = {
 	},
     script: [
         { url: 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js' },  
-        { content: "mermaid.initialize({ startOnLoad: false, themeVariables: { fontSize: '14px', fontFamily: 'Yu Gothic UI, system-ui' } }); (async () => { await mermaid.run(); })();" }
+        { content: "mermaid.initialize({ startOnLoad: false, themeVariables: { fontSize: '14px', fontFamily: 'Yu Gothic UI, system-ui' } }); (async () => { await mermaid.run(); })();" },
+        { url: 'https://cdn.jsdelivr.net/npm/katex/dist/katex.min.js' },
+        { url: 'https://cdn.jsdelivr.net/npm/marked-katex-extension/lib/index.umd.js' },
     ],
 	stylesheet_encoding: 'utf-8',
 };

package.json

@@ -1,4 +1,5 @@
 {
+    "type": "commonjs",
     "scripts": {
         "build": "run-s build:* --continue-on-error --print-label",
         "build:document-template": "npx md-to-pdf --config-file ./md-to-pdf-config.js ./docs/_document-template/contents.md",
@@ -12,6 +13,7 @@
         "cspell-cli": "^8.16.1",
         "markdownlint-cli2": "^0.16.0",
         "marked-admonition-extension": "^0.0.4",
+        "marked-katex-extension": "^5.1.3",
         "md-to-pdf": "^5.2.4",
         "npm-run-all2": "^7.0.1",
         "sudachi-synonyms-dictionary": "^14.0.0",

pdf-sample.md

@@ -82,3 +82,12 @@ PDF 上でチェックボックスのオン / オフを切り替えることは
 全部で 16 種類のアラートが利用できます。
 
 ![アラートのサンプル](https://github.com/user-attachments/assets/3c4cc088-5c23-40fb-9e63-80b0c4aaadb3)
+
+## 数式
+
+[KaTeX](https://katex.org/) を使って数式を記述できます。
+インライン要素、ブロック要素、どちらにも対応しています。
+
+![数式（インライン要素）のサンプル](https://github.com/user-attachments/assets/34f62912-1946-43e8-b95a-93d544fcbe8b)
+
+![数式（ブロック要素）のサンプル](https://github.com/user-attachments/assets/f987245c-9fae-4c30-8743-750a87ede06d)