markdown-it-mathjax3-pro

一个功能强大的 markdown-it 插件，支持 MathJax 3，具有增强功能，支持服务器端渲染 (SSR) 和客户端渲染 (CSR) 模式。

特性

• 🚀 双重渲染模式：支持 SSR 和 CSR 两种模式
• 🎯 性能增强：为多个数学表达式优化的批处理
• 🎨 灵活输出：支持 SVG 和 CHTML 输出格式
• 📝 自定义分隔符：可配置的数学分隔符
• 🔧 TypeScript 支持：完整的 TypeScript 支持和类型定义
• 📦 零配置：开箱即用，具有合理的默认设置

快速开始

安装

npm install markdown-it-mathjax3-pro

基本用法

import MarkdownIt from 'markdown-it';
import MarkdownItMathJaX3PRO from 'markdown-it-mathjax3-pro';

const md = MarkdownIt().use(MarkdownItMathJaX3PRO);

const markdown = `
行内数学公式：$E = mc^2$

块级数学公式：
$$
\\frac{d}{dx}\\int_{a}^{x} f(t)dt = f(x)
$$
`;

const result = md.render(markdown);
console.log(result);

项目配置

插件接受各种配置选项：

服务器端渲染（默认）

const md = MarkdownIt().use(MarkdownItMathJaX3PRO, {
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']],
    displayMath: [['$$', '$$'], ['\\[', '\\]']],
    tags: 'ams',
    packages: ['base', 'ams', 'newcommand', 'configmacros']
  },
  chtml: {
    fontURL: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/output/chtml/fonts/woff-v2'
  },
  // 使用 SVG 输出代替 CHTML
  svg: {
    fontCache: 'local',
    displayAlign: 'center'
  }
});

客户端渲染

const md = MarkdownIt().use(MarkdownItMathJaX3PRO, {
  user_side: true,
  mathjax_options: {
    enableMenu: true,
    // 其他 MathJax 选项
  }
});

配置选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | user_side | boolean | false | 启用客户端渲染模式 | | tex | object | {...} | TeX 输入处理器选项 | | tex.inlineMath | array | [['$', '$']] | 行内数学分隔符 | | tex.displayMath | array | [['$$', '$$']] | 块级数学分隔符 | | chtml | object | {...} | CHTML 输出选项 | | svg | object | undefined | SVG 输出选项（提供时使用 SVG 代替 CHTML） | | mathjax_options | object | {} | 客户端 MathJax 配置 |

技术实现原理与 markdown-it-mathjax3 的区别和优势

与 markdown-it-mathjax3 的主要区别

1. 双模式支持

   • SSR 模式：使用 MathJax-full 在服务器上预渲染数学表达式
   • CSR 模式：注入 MathJax 脚本进行客户端渲染

2. 批处理机制

   • 在单个 MathJax 文档中处理所有数学表达式
   • 显著提高包含多个公式的文档的性能

3. 增强的灵活性

   • 支持 SVG 和 CHTML 输出格式
   • 可配置的数学分隔符
   • 更好的错误处理和验证

4. 样式表管理

   • 自动提取和注入 CSS 样式
   • 支持框架集成的 frontmatter 注入

架构设计

输入 Markdown
     ↓
解析数学标记（行内和块级）
     ↓
使用 MathJax 批处理
     ↓
用渲染的 HTML 替换标记
     ↓
注入样式表
     ↓
输出 HTML

示例

完整的自定义配置示例

See test.ts for details

客户端渲染示例

详见test4csr.ts

Vitepress example

ServerSide mode:

export default defineConfig({
  title: "neonexus",
  description: "docs for neonexus",
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag) => tag.includes('mjx-')
      }
    }
  },
  markdown: {
    config: (md) => {
      md.use(mathjax3, {
        // add new inlineMathSeparator && displayMathSeparator
        tex: {
          inlineMath: [['$', '$'], ['§', '§']],
          displayMath: [['$$', '$$'], ['§§', '§§']],
        },
        //enable chtml mode 
        chtml: {
          fontURL: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/output/chtml/fonts/woff-v2'
        }
      })
    },
    theme: {
      light: "catppuccin-latte",
      dark: "catppuccin-macchiato",
    },
  },
  //inject ccs to head for mathjax
  transformPageData(pageData) {
    const head = (pageData.frontmatter.head ??= []);
    const inject_content = pageData.frontmatter.inject_content;
    if (inject_content && Array.isArray(inject_content)) {
      inject_content.forEach(item => {
        const { type, contribution, content } = item;
        const headEntry = [type, contribution || {}, content || ''].filter(Boolean);
        head.push(headEntry as HeadConfig);
      });

      delete pageData.frontmatter.inject_content;
    }
  },
})

UserSide mode:

export default defineConfig({
  title: "your name",
  description: "docs for wahtever",
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag) => tag.includes('mjx-')
      }
    }
  },
  markdown: {
    config: (md) => {
      md.use(mathjax3, {
        user_side: true,
      })
    },
  },
  //inject for mathjax script
  transformPageData(pageData) {
    const head = (pageData.frontmatter.head ??= []);
    const inject_content = pageData.frontmatter.inject_content;
    if (inject_content && Array.isArray(inject_content)) {
      inject_content.forEach(item => {
        const { type, contribution, content } = item;
        const headEntry = [type, contribution || {}, content || ''].filter(Boolean);
        head.push(headEntry as HeadConfig);
      });
      delete pageData.frontmatter.inject_content;
    }
  },
})

许可证

MIT

贡献

欢迎贡献！请随时提交 Pull Request。

支持

如果您有任何问题或疑问，请在 GitHub 上提出 issue。