Merge pull request #53 from devlive-community/dev-archive

支持 KaTeX 渲染 (close #10)

docs/content/usage/katex.md

@@ -0,0 +1,71 @@
+---
+title: KaTeX
+icon: square-function
+---
+
+PageForge 支持使用 [KaTeX](https://katex.org "KaTeX" "_blank") 数学公式渲染引擎。
+
+!!! danger "注意"
+    该功能需要在配置文件中启用，可以在 `pageforge.yaml` 中配置
+
+    ```yaml
+    feature:
+      katex:
+        enable: true
+    ```
+
+    如果要传递自定义配置可以在 `pageforge.yaml` 中添加自定义配置
+
+    ```yaml
+    feature:
+      katex:
+        enable: true
+        options:
+          throwOnError: true
+    ```
+!!!
+
+## CDN 配置
+
+---
+
+PageForge 默认使用的是以下 CDN
+
+```js
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css">
+<script src="https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.js"></script>
+```
+
+可以修改 `pageforge.yaml` 中的 `cdn` 配置来配置自定义 CDN
+
+```yaml
+cdn:
+  katexJs: "https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.js"
+  katexCss: "https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css"
+```
+
+## 基本语法
+
+---
+
+```markdown
+:::katex
+\sum_{i=1}^n i = \frac{n(n+1)}{2}
+:::
+```
+
+## 化学方程式
+
+---
+
+:::katex
+\ce{CO2 + C -> 2 CO}
+:::
+
+## 带编号的公式
+
+---
+
+:::katex
+\tag{1} E = mc^2
+:::

docs/pageforge.yaml

@@ -95,6 +95,8 @@ feature:
     enable: true
   grid:
     enable: true
+  katex:
+    enable: true
 
 i18n:
   default: zh-CN
@@ -196,6 +198,7 @@ nav:
       - /usage/icon
       - /usage/grid
       - /usage/api
+      - /usage/katex
   - Template:
       - /template/home
       - /template/team

lib/extension/marked/pageforge-katex.js

@@ -0,0 +1,56 @@
+const {loadComponent} = require("../../component-loader");
+const ConfigManager = require("../../config-manager");
+const config = new ConfigManager(process.cwd()).getConfig();
+
+const PageForgeKaTeXExtension = {
+    name: 'pageforgeKatex',
+    level: 'block',
+
+    start(src) {
+        if (!config.feature?.katex?.enable) {
+            return -1;
+        }
+
+        // 匹配 :::katex 或 ::: katex 开头
+        const match = src.match(/^:::\s*katex\n/m);
+        return match ? match.index : -1;
+    },
+
+    tokenizer(src, tokens) {
+        if (!config.feature?.katex?.enable) {
+            return false;
+        }
+
+        // 匹配开头
+        const match = src.match(/^:::\s*katex\n/);
+        if (!match) {
+            return false;
+        }
+
+        // 查找结束标记 :::
+        const endIndex = src.indexOf('\n:::');
+        if (endIndex === -1) {
+            return false;
+        }
+
+        // 提取内容
+        const content = src.slice(match[0].length, endIndex).trim();
+        const raw = src.slice(0, endIndex + 4);
+
+        return {
+            type: 'pageforgeKatex',
+            raw,
+            content,
+            tokens: []
+        };
+    },
+
+    renderer(token) {
+        return loadComponent('katex', {
+            content: token.content,
+            config: config.feature?.katex?.options || {}
+        });
+    }
+};
+
+module.exports = PageForgeKaTeXExtension;

lib/extension/marked/pageforge-marked.js

@@ -17,6 +17,7 @@ const PageForgeButtonExtension = require("./pageforge-button");
 const PageForgeIconExtension = require("./pageforge-icon");
 const PageForgeGridExtension = require('./pageforge-grid')
 const PageForgeRestApiExtension = require('./pageforge-api')
+const PageForgeKaTeXExtension = require('./pageforge-katex')
 const {unescape} = require('./utils')
 
 const renderer = {
@@ -93,7 +94,8 @@ marked.use({
         PageForgeButtonExtension,
         PageForgeIconExtension,
         PageForgeGridExtension,
-        PageForgeRestApiExtension
+        PageForgeRestApiExtension,
+        PageForgeKaTeXExtension
     ],
     renderer,
     breaks: false

templates/components/katex.js

@@ -0,0 +1,18 @@
+module.exports = function template(item) {
+    return `
+        <div class="katex-wrapper my-4">
+            <div class="katex-formula overflow-x-auto">
+                <script>
+                    document.currentScript.parentElement.innerHTML = katex.renderToString(
+                        \`${item.content}\`, 
+                        {
+                            displayMode: true,
+                            throwOnError: false,
+                            ...${JSON.stringify(item.config || {})}
+                        }
+                    );
+                </script>
+            </div>
+        </div>
+    `;
+};

templates/layouts/base.ejs

@@ -1,6 +1,6 @@
 <%
 if (pageData.template === 'team') {
-    pageData.config = { toc: false, sidebar: false };
+    pageData.config = {toc: false, sidebar: false};
 }
 
 // 构建静态资源路径函数（只考虑版本）
@@ -63,7 +63,8 @@ function buildPagePath(pagePath) {
                     if (/^\d+\.\d+(\.\d+)?$/.test(pathParts[0]) || pathParts[0] === 'current') {
                         version = pathParts[0];
                         lang = pathParts[1];
-                    } else {
+                    }
+                    else {
                         lang = pathParts[0];
                     }
                 }
@@ -82,7 +83,8 @@ function buildPagePath(pagePath) {
                     .then(response => {
                         if (response.ok) {
                             window.location.href = href;
-                        } else {
+                        }
+                        else {
                             window.location.href = notFoundPath;
                         }
                     })
@@ -115,6 +117,12 @@ function buildPagePath(pagePath) {
     <% if (locals.siteData.feature?.mermaid?.enable) { %>
         <script src="<%= locals.siteData.cdn?.mermaidJs || 'https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.min.js' %>"></script>
     <% } %>
+
+    <!-- KaTeX 数学公式 -->
+    <% if (locals.siteData.feature?.katex?.enable) { %>
+        <link rel="stylesheet" href="<%= locals.siteData.cdn?.katexCss || 'https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css' %>">
+        <script src="<%= locals.siteData.cdn?.katexJs || 'https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.js' %>"></script>
+    <% } %>
 </head>
 
 <body class="min-h-screen bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">