susam/texme · 上手攻略

仓库：susam/texme
链接：https://github.com/susam/texme
分类：Markdown + LaTeX 渲染工具 · 自渲染文档
作者：Jay
更新：2026-08-20

这是什么

TeXMe 是一个极简的 JavaScript 工具，用于创建自渲染 Markdown + LaTeX 文档。它的核心思路是：在 .html 文件里写 Markdown 内容，然后在任意浏览器中打开——页面自带一行 <script> 标签，就能自动把 Markdown 渲染成 HTML、把 LaTeX 公式渲染成 MathJax，整个过程无需任何构建步骤、服务器或本地安装。

本质上，它解决的是"我想写一份带数学公式的文档，能在浏览器里直接看"的轻量需求，而不是"我要搭一整套文档系统"的重型需求。

解决什么问题

写技术文档时，常见的选择有：

纯 Markdown：不支持 LaTeX 数学公式（除非配合额外插件）
Jupyter Notebook：需要 Python 环境 + nbconvert，交付物是 .ipynb 不方便直接分享
LaTeX：公式能力最强，但写作门槛高，PDF 输出不适合网页直接嵌入
pandoc：命令行转换工具，引入额外依赖

TeXMe 的切入点是：只要你会写 Markdown，会一点 LaTeX 语法，就能生成一个.html文件——打开浏览器就能看到带数学公式的完整渲染结果。无需安装、无需构建、直接分享 URL 或文件。

快速安装

TeXMe 不需要安装。它通过 CDN 加载，无需任何本地环境。

方式一：最短示例（最常用）

创建一个扩展名为 .html 的文件，粘贴以下内容：

<!DOCTYPE html><script src="https://cdn.jsdelivr.net/npm/texme@1.2.2"></script><textarea>

# Euler's Identity

In mathematics, **Euler's identity** is the equality
$$ e^{i\pi} + 1 = 0. $$

## Explanation

Euler's identity is a special case of Euler's formula from complex
analysis, which states that for any real number $x$:
$$ e^{ix} = \cos x + i\sin x. $$

</textarea>

直接用浏览器打开这个 .html 文件，页面会自动渲染 Markdown + LaTeX。

⚠️ 版本号：texme@1.2.2 是当前文档化版本。请以 npm 页面或 GitHub Releases 上标明的 latest 版本为准。

方式二：CDN 变体

<!-- 固定版本（已知 1.2.2 为文档化版本） -->
<script src="https://cdn.jsdelivr.net/npm/texme@1.2.2"></script>

<!-- 始终加载最新版本（可能与文档化版本不一致，有风险）-->
<script src="https://cdn.jsdelivr.net/npm/texme"></script>

<!-- unpkg CDN -->
<script src="https://unpkg.com/texme"></script>

方式三：自托管

下载 texme.js 文件，在自己的服务器上托管：

<script src="/path/to/texme-1.2.2.js"></script>

下载链接：https://cdn.jsdelivr.net/npm/texme@1.2.2/ 或 GitHub Releases 页面。

核心用法

标准完整模板（推荐生产使用）

<!DOCTYPE html>
<html lang="en">
<title>Notes on Euler's Identity</title>
<script src="https://cdn.jsdelivr.net/npm/texme@1.2.2"></script>
<textarea>

# Euler's Identity

In mathematics, **Euler's identity** is the equality
$$ e^{i\pi} + 1 = 0. $$

## Explanation

Euler's identity is a special case of Euler's formula:
$$ e^{ix} = \cos x + i\sin x. $$

Setting $x = \pi$ yields $e^{i\pi} = -1$, hence the identity.

</textarea>

这个版本能通过 W3C HTML5 验证器验证，是兼顾简洁性和规范正确性的推荐写法。

三种样式模式

TeXMe 通过 window.texme.style 配置渲染样式：

样式	配置值	效果
查看器样式（默认）	`'viewer'`	白色渲染区 + 灰色背景，适合阅读
简洁白色	`'plain'`	纯白背景，无边框
无样式	`'none'`	关闭默认样式，可完全自定义 CSS

<script>window.texme = { style: 'plain' }</script>
<script src="https://cdn.jsdelivr.net/npm/texme@1.2.2"></script><textarea>
...
</textarea>

仅渲染 Markdown（无数学公式）

如果文档不需要 LaTeX，可以禁用 MathJax 加速加载：

<script>window.texme = { useMathJax: false, protectMath: false }</script>
<script src="https://cdn.jsdelivr.net/npm/texme@1.2.2"></script><textarea>
...
</textarea>

手动控制渲染时机

默认加载后立即渲染。设置为手动渲染：

<script>window.texme = { renderOnLoad: false }</script>
<script src="https://cdn.jsdelivr.net/npm/texme@1.2.2"></script>
<script>
  window.onload = function () {
    document.getElementById('renderBtn').onclick = function () {
      texme.renderPage();
    };
  };
</script>
<textarea>
# Title
...
</textarea>
<button id="renderBtn">Render</button>

加载后设置选项（需先跳过自动渲染）：

texme.setOption('style', 'plain');
texme.renderPage();

内容写在 body 里（不用 textarea）

# Euler's Identity

$$ e^{i\pi} + 1 = 0. $$

<script src="https://cdn.jsdelivr.net/npm/texme@1.2.2"></script>

⚠️ 这种写法更简洁，但风险是内容写在 HTML <body> 里——如果内容本身包含 HTML 语法错误的字符序列，浏览器会把它们当作真正的 HTML 解析，导致渲染结果损坏。敏感内容建议用 textarea 方式。

保护 LaTeX 分隔符（Markdown 优先级）

如果 Markdown 代码块或图片描述中包含 $ 或 $$ 等 LaTeX 分隔符，TeXMe 可能会误渲染它们。用 md 环境包裹：

\begin{md}
`echo $foo`   <!-- $foo 不会被当作 LaTeX -->
\end{md}

典型适用场景

技术博客/课程讲义：需要展示数学推导，但受众没有 LaTeX 环境；可以直接发 .html 文件链接。
学术笔记：研究者之间分享带公式的笔记，不需要 Overleaf 或 LaTeX 发行版。
面试/刷题题解：在浏览器里直接展示算法复杂度和推导过程，带 MathJax 渲染。
静态网站嵌入：在 Hugo、Jekyll 等静态网站中，*.html 文件可作为独立页面直接托管，不依赖服务端渲染。
快速原型：写论文时的公式原型，不需要每次 pdflatex 编译，刷新浏览器即可看结果。

坑与注意

LaTeX 分隔符冲突：Markdown 代码块（反引号）中如果写了 $ 符号，TeXMe 会尝试将其作为 LaTeX 渲染。解决方案是用 md 环境包裹代码块，或者对 $ 做 HTML 转义。
MathJax 加载时间：TeXMe 依赖 MathJax CDN，如果网络无法访问 jsDelivr，公式会显示为原始 LaTeX 源码。自托管 texme.js + 内嵌 MathJax 可以解决离线使用问题。
HTML 内容在 body 里可能被浏览器解析：如上所述，内容写在 body 里 这种写法在内容含 HTML 语法字符时可能产生意外渲染；文档本身推荐使用 textarea 方式。
页面标题自动设置规则：TeXMe 用内容第一个非空行（去除 # 和首尾空白）自动设置为 <title>；如果不想要这个行为，需要在 <head> 中显式定义 <title> 元素。
CSS 定制有限制：默认 viewer 样式会在渲染区外包裹灰色背景；如果要自定义 CSS，需要将 style 设为 'none' 然后自己写 CSS，否则样式会被 viewer 默认覆盖。
多文件之间的样式不隔离：TeXMe 默认样式作用于全局 body，在同一个页面嵌入多个 TeXMe 文档可能会有样式冲突。

与同类对比

对比项	TeXMe	Pandoc（+ LaTeX）	Marked + KaTeX/MathJax	Marp
零安装/零构建	✅ 纯 CDN	❌ 需要命令行工具	⚠️ 需要 npm + 脚本	⚠️ 需要 CLI
输出格式	单 HTML 文件	PDF/HTML/DOCX	自搭 HTML	PPTX/HTML/PDF
MathJax 内置	✅	❌（需要模板）	⚠️ 需单独引入	✅
自渲染（.html 打开即渲染）	✅	❌	❌	❌
自定义 CSS	⚠️ 需禁用默认样式	✅ LaTeX 模板	✅ 完全可控	⚠️ 受主题限制
LaTeX 完整性	MathJax 3（现代）	完整 LaTeX	KaTeX 或 MathJax	MathJax
适用场景	轻量笔记/博客	正式学术论文	程序员自建博客	演示幻灯片

⚠️ TeXMe 的 LaTeX 能力上限是 MathJax 3，不支持完整 LaTeX 命令（如 \newenvironment、TikZ 等需要 LaTeX 引擎的功能）。

一句话推荐结论

如果你需要一个零配置、零安装、在任何浏览器里打开就能看 Markdown + 数学公式的文档工具，TeXMe 是最简洁的选择——写一个 .html 文件、加一行 CDN script 标签，就能随时分享带漂亮公式的笔记；但它的能力上限是 MathJax 3，不适合需要完整 LaTeX 功能的正式学术出版场景。

来源：GitHub README（susam/texme）+ npm 页面+ TeXMe 官方示例