@mathcrowd/mmarked
v3.1.3
Published
A customized markdown parser/renderer with tex2svg.
Readme
mmarked
English | 在线演示 | VSCode 扩展 | Logseq 插件
📖 概述
用 mmarked 改变你的 Markdown 体验 —— 一个专为教育和数学内容设计的强大 TypeScript 库。支持实时渲染复杂 LaTeX 公式、定理块和自定义教育语法。
完美适用于：
- 📚 教育工作者 制作数学课程材料
- 🎓 学生 撰写技术笔记和作业
- 📝 研究人员 编写学术论文
- 💻 开发者 构建教育平台
- 💡 任何人 在 Markdown 中使用数学符号
✨ 功能特性
核心能力
- ✅ 完整 CommonMark 支持 - 与标准 Markdown 语法完全兼容
- 🔗 轻松集成 - 在 Node.js 和浏览器环境中无缝运行
- 📦 轻量核心 - 最少依赖，可扩展架构
- ⚡ 高性能 - 优化的渲染管道，输出快速
数学内容
- 🧮 高级 LaTeX 渲染 - 由 MathJax 驱动，呈现专业品质的公式
- 📐 TeX 转 SVG - 高质量 SVG 格式的方程输出
- 🔢 自动编号脚注 - 易用的引用系统，自动编号
教育功能
- 📘 定理样式块 - 专用语法支持定理、引理、定义和例子
- 自动编号支持
- 使用
[~id]语法进行交叉引用 - 可自定义标题
- 🔍 可折叠解答块 - 通过切换功能隐藏/显示答案和证明
- 🎯 语法高亮 - highlight.js 增强的代码块
媒体与自定义
- 🖼️ 增强图片 - 使用简单的
=宽x高语法灵活调整尺寸 - 📹 视频支持 - 视频元素支持相同的尺寸选项
- 🎨 可扩展 - 基于 marked.js 构建，易于自定义
🚀 快速开始
安装
npm install @mathcrowd/mmarked mathjax-full highlight.js基本用法
import { renderMarkdown } from '@mathcrowd/mmarked'
// 渲染带 LaTeX 支持的 Markdown
const result = renderMarkdown(`
# 勾股定理
\`\`\`[theorem,pythagoras,勾股定理]
对于直角三角形，设两直角边为 $a$、$b$，斜边为 $c$：
$$a^2 + b^2 = c^2$$
\`\`\`
这个基本定理（见 [~pythagoras]）描述了直角三角形边长的关系。
`)
console.log(result.parsed) // HTML 输出
console.log(result.time) // 渲染耗时（毫秒）许可证配置（仅 Node.js）
重要提示： 许可证验证仅适用于 Node.js 服务端使用。浏览器环境不需要配置许可证。
在 Node.js 应用中商业使用时，必须配置有效的许可证：
import { configureLicense, renderMarkdown } from '@mathcrowd/mmarked'
// 配置你的许可证（在应用启动时执行一次）
configureLicense({
apiKey: 'MMARKED-XXXX-XXXX-XXXX-XXXX'
})
// 现在可以使用库了
const result = renderMarkdown('# Hello World')在 Node.js 中未配置许可证：
import { renderMarkdown } from '@mathcrowd/mmarked'
// 可以正常工作，但会在控制台显示警告
const result = renderMarkdown('# Hello')
// 控制台输出：
// ⚠️ 未配置 Node.js 服务端有效许可证。
// 商业使用请通过 configureLicense() 配置许可证。
// 联系 [email protected] 获取商业许可。
// 浏览器使用无需许可证。系统要求：
- Node.js 18+ 用于远程许可证验证（使用 fetch API）
获取许可证：
- 📧 邮箱：[email protected]
- 🌐 访问：lab.mathcrowd.cn
浏览器端使用
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>mmarked 演示</title>
</head>
<body>
<div id="content"></div>
<script type="module">
import { renderMarkdown } from 'https://cdn.jsdelivr.net/npm/@mathcrowd/mmarked/dist/index.mjs'
const markdown = `
# 爱因斯坦质能方程
著名的方程 $E = mc^2$ 描述了能量与质量的关系。
**其中：**
- $E$ 是能量
- $m$ 是质量
- $c$ 是光速
`
document.getElementById('content').innerHTML = renderMarkdown(markdown).parsed
</script>
</body>
</html>📚 扩展语法指南
自动编号的定理块
\`\`\`[theorem,fermat,费马大定理]
对于任意大于 2 的整数 $n$，不存在正整数 $a$、$b$、$c$
使得 $a^n + b^n = c^n$。
\`\`\`
\`\`\`[lemma,helper,辅助引理]
这个引理支持 [~fermat] 的证明。
\`\`\`支持的块类型： theorem（定理）、lemma（引理）、corollary（推论）、axiom（公理）、definition（定义）、example（例）
自定义块： 使用任何关键字创建自定义定理样式块，独立编号。
隐藏编号： 在关键字后添加 *（如 theorem*）可隐藏编号，但保持序列。
交互式解答块
**问题：** 解方程 $x^2 - 5x + 6 = 0$
~~~[solution]
**解答：**
因式分解方程：
$$(x-2)(x-3) = 0$$
因此，解为：
- $x = 2$
- $x = 3$
~~~
~~~[proof]
**验证：** 代入 $x=2$：$(2)^2 - 5(2) + 6 = 4 - 10 + 6 = 0$ ✓
~~~增强的图片和视频
自动编号脚注
黎曼猜想[^riemann]是最重要的未解决问题之一。
另一个著名猜想是孪生素数猜想[^twin]。
[^riemann]: 由伯恩哈德·黎曼于 1859 年提出。
[^twin]: 指出存在无穷多对孪生素数。🔧 API 参考
许可证管理（仅 Node.js）
configureLicense(config: LicenseConfig)
为 Node.js 环境中的商业使用配置许可证。必须在使用渲染函数之前调用。
参数：
interface LicenseConfig {
apiKey: string // 你的许可证密钥（格式：MMARKED-XXXX-XXXX-XXXX-XXXX）
}示例：
// 最简配置（推荐）
configureLicense({
apiKey: 'MMARKED-XXXX-XXXX-XXXX-XXXX'
})核心函数
renderMarkdown(markdown: string)
将 Markdown 渲染为 HTML，支持所有功能。
许可证： Node.js 商业使用需要有效许可证。浏览器免费使用。
返回值：
{
parsed: string, // HTML 输出
lexed: Token[], // Marked.js 令牌
time: number // 渲染时间（毫秒）
}示例：
const { parsed, time } = renderMarkdown('# 你好 $x^2$')
console.log(`渲染耗时 ${time}ms`)renderMarkdownCompact(markdown: string)
渲染 Markdown 但不包裹 <p> 标签，适合行内内容。
许可证： Node.js 商业使用需要有效许可证。浏览器免费使用。
返回值： 与 renderMarkdown() 相同的结构
使用场景： 渲染单行内容，不需要块级元素。
const { parsed } = renderMarkdownCompact('**粗体** 和 $x^2$ 行内')
// 输出: <strong>粗体</strong> 和 <svg>...</svg> 行内tex2svg(html: string): string
将 HTML 中的 LaTeX 表达式转换为 SVG。
参数：
html: 包含 LaTeX 表达式的 HTML 字符串（$...$表示行内，$$...$$表示块）
返回值： LaTeX 转换为 SVG 图形后的 HTML
示例：
const html = '<p>爱因斯坦：$E=mc^2$</p>'
const withSvg = tex2svg(html)⚠️ 安全警告
始终使用 DOMPurify 清理 HTML 输出，然后再插入到 DOM 中：
import DOMPurify from 'dompurify'
import { renderMarkdown } from '@mathcrowd/mmarked'
// 安全渲染用户输入
const userMarkdown = getUserInput()
const { parsed } = renderMarkdown(userMarkdown)
const safeHtml = DOMPurify.sanitize(parsed)
document.getElementById('content').innerHTML = safeHtml🔌 编辑器集成
通过官方集成增强编辑体验：
📖 文档与资源
🏗️ 技术栈
- marked.js - 快速 Markdown 解析器
- MathJax - 精美数学渲染
- highlight.js - 语法高亮
🏢 关于橘子数学
橘子数学（Mathcrowd） 致力于通过创新技术革新中国的数学教育。我们由经验丰富的开发者和数学教育工作者创立，正在构建工具和社区，让数学学习更易获取、更有吸引力。
- 🌐 Mathcrowd Labs: lab.mathcrowd.cn
- 💬 加入 Discord： discord.gg/6VMUVA5Yq2
📄 许可证
采用 CC BY-NC 4.0 许可 - 非商业用途免费。
商业许可请联系：[email protected]
💬 支持
- 🐛 错误报告： GitHub Issues
由 橘子数学 团队用 ❤️ 打造