Merge pull request #31 from tsuna-can-se/development

v1.1.0 リリース準備

.github/release.yml

@@ -0,0 +1,30 @@
+changelog:
+  categories:
+    - title: ':newspaper: Features'
+      labels:
+        - '*'
+      exclude:
+        labels:
+          - bug
+          - dependencies
+          - internal improvement
+          - release
+    - title: ':wrench: Bug fixes'
+      labels:
+        - bug
+    - title: ':label: :green_circle: GtiHub Actions task dependencies'
+      labels:
+        - CI/CD
+    - title: ':label: :white_circle: npm package dependencies'
+      labels:
+        - npm
+    - title: ':label: Other dependencies'
+      labels:
+        - dependencies
+      exclude:
+        labels:
+          - CI/CD
+          - npm
+    - title: ':lollipop: improvements in development'
+      labels:
+        - internal improvement

cspell.json

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

docs/_document-template/contents.md

@@ -39,6 +39,8 @@ dest: ./output/ドキュメントテンプレート.pdf
     - [2.7. インラインコード](#27-インラインコード)
     - [2.8. リンク](#28-リンク)
     - [2.9. 画像](#29-画像)
+        - [2.9.1. 画像ファイル](#291-画像ファイル)
+        - [2.9.2. mermaid](#292-mermaid)
     - [2.10. テーブル](#210-テーブル)
     - [2.11. 箇条書き](#211-箇条書き)
     - [2.12. タスクリスト](#212-タスクリスト)
@@ -47,6 +49,7 @@ dest: ./output/ドキュメントテンプレート.pdf
     - [2.15. 水平線](#215-水平線)
     - [2.16. エスケープ](#216-エスケープ)
     - [2.17. アラート](#217-アラート)
+    - [2.18. 数式](#218-数式)
 - [3. 参考資料](#3-参考資料)
 
 # 1. ドキュメントの全体設定
@@ -252,6 +255,8 @@ URL を `< >` で囲うと、そのままリンクにできます。
 
 ## 2.9. 画像
 
+### 2.9.1. 画像ファイル
+
 画像は draw.io で作成した SVG 画像を使用してください。
 \*.drawio ファイルと、作成した \*.svg ファイルを images フォルダーに配置します。
 画像内に文字を入れる場合は、フォントを `Yu Gothic UI` に、フォントサイズを 16 ポイントに設定してください。
@@ -266,6 +271,8 @@ URL を `< >` で囲うと、そのままリンクにできます。
 
 ![demo 画像](/docs/_document-template/images/demo.svg)
 
+### 2.9.2. mermaid
+
 簡単な図は、 [mermaid](https://mermaid.js.org/) で作成できます ( Beta )。
 ` ```mermaid ～ ``` ` で囲った範囲に mermaid 記法で図を記述できます。
 
@@ -565,6 +572,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,8 +13,9 @@
         "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",
+        "npm-run-all2": "^7.0.2",
         "sudachi-synonyms-dictionary": "^14.0.0",
         "textlint": "^14.4.0",
         "textlint-filter-rule-comments": "^1.2.2",

pdf-sample.md

@@ -41,11 +41,11 @@
 
 \*\.svg 形式のファイルにも対応しています。
 
-![画像貼り付けのサンプル](https://github.com/user-attachments/assets/9dbf143c-d536-4c35-aedf-fe3f2839795b)
+![画像貼り付けのサンプル](https://github.com/user-attachments/assets/07502d0d-2491-4ac9-8b68-402074b0a020)
 
 [Mermaid](https://mermaid.js.org/) の構文を入れることもできます。
 
-![Mermaid のサンプル](https://github.com/user-attachments/assets/8f896815-0346-403c-a330-cac7bb01dd8f)
+![Mermaid のサンプル](https://github.com/user-attachments/assets/7546d248-6fba-45e6-99a6-fbe35156da0a)
 
 ## テーブル
 
@@ -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)