markdown-it-texmath 技术文档

markdown-it-texmath 是一个专为 Markdown 文档设计的插件，它让你能够轻松地在文档中嵌入 TeX 数学公式，并利用 KaTeX 快速渲染数学表达式。本文档旨在指导你完成从安装到使用的整个过程，并详细介绍其功能和API。

安装指南

Node.js环境

在你的项目中使用npm来安装markdown-it-texmath及其依赖：

npm install markdown-it-texmath markdown-it katex

这将确保markdown-it、markdown-it-texmath以及快速渲染数学公式的Katex一同被安装。

浏览器环境

对于Web项目，你可以通过CDN直接引入必要的文件：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css">
<script src="https://cdn.jsdelivr.net/npm/markdown-it/dist/markdown-it.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/markdown-it-texmath/texmath.min.js"></script>

项目使用说明

在Node.js中使用

安装完成后，在你的代码中引入并配置markdown-it以使用markdown-it-texmath插件：

const markdownIt = require('markdown-it');
const texmath = require('markdown-it-texmath');

// 初始化markdown-it实例并启用texmath插件
const md = markdownIt({ html: true })
           .use(texmath, {
               engine: require('katex'),
               delimiters: 'dollars', // 或者选择其他模式
               katexOptions: { macros: {"\\RR": "\\mathbb{R}"} } // 可选的KaTeX选项
           });

// 渲染包含数学公式的Markdown文本
let renderedHTML = md.render('这是一个示例公式：$e^{iπ}+1=0$');
console.log(renderedHTML);

在浏览器中使用

在HTML文件中设置好markdown-it和markdown-it-texmath后，可通过以下方式使用：

<script>
    document.addEventListener('DOMContentLoaded', function() {
        let md = markdownIt({ html: true })
                 .use(texmath, {
                     engine: katex, // 假定katex已经被加载
                     delimiters: 'dollars'
                 });
        
        let str = '公式测试：$e^{iπ}+1=0$';
        document.getElementById('output').innerHTML = md.render(str);
    });
</script>

<div id="output"></div>

项目API使用文档

markdown-it-texmath主要通过在markdown-it实例上使用.use(texmath, options)方法进行配置，其中options可以包括：

• engine (require('katex')) - 指定使用的数学渲染引擎，默认是KaTeX。
• delimiters ('dollars', 'brackets', 'doxygen', 'gitlab', 'julia', 'kramdown', 'beg_end') - 设置公式的分隔符类型。
• katexOptions - 直接传递给Katex的选项对象，用于自定义渲染行为。

项目特点

• 支持多种分隔符风格，以适应不同用户的写作习惯。
• 内置简单的公式的自动编号。
• 兼容性良好，支持包括表格、列表在内的复杂Markdown结构中的内联数学公式。
• 提供了宏支持，方便扩展公式的书写。

markdown-it-texmath简化了在Markdown文档中插入复杂数学公式的过程，特别适合科研人员、工程师和学生群体。希望这篇文档能帮助你高效利用此工具。