reveal.js 集成代码高亮与数学公式插件教程

一、插件架构与渲染运行机制

reveal.js 采用松耦合的插件化设计，其核心引擎仅负责幻灯片翻页、动画时序切换、全屏及基础 DOM 结构管理。所有针对特定内容类型的扩展能力均通过插件注册通道接入。在底层，无论是代码高亮还是数学公式解析，均遵循“初始化阶段注册 → 扫描匹配当前文档 DOM → 动态重写节点内容”的标准生命周期。

代码高亮插件基于著名的 highlight.js 引擎封装。当幻灯片载入或切换时，它会自动匹配所有带有 <pre><code> 标记的节点，依据声明的语言类名进行语法分词，并自动将文本拆分成包含多种 CSS 选择器的 <span class="hljs-*"> 节点。如果配置了行号属性，插件还会进一步注入行列标记并监听键盘切换事件。

数学公式插件 RevealMath 则提供对 KaTeX 或 MathJax 的封装。在幻灯片初始化期间，插件会依据配置选择渲染后端，自动拉取或连接对应的数学解析器脚本，遍历 DOM 中的特定分隔符（例如 $ ... $ 表示行内公式，\[ ... \] 或 $$ ... $$ 表示块级公式），将其编译为基于矢量数学符号的专用 DOM 树或内联 SVG。

图 1：reveal.js 插件注册与页面元素动态转译架构

二、集成实操四步流程

要在一个静态页面或已有 reveal.js 项目中正确启用这两个插件，需要按照“资源依赖引入 → 幻灯片内容标记 → 脚本挂载与初始化 → 渲染校验”四个步骤有序执行。

图 2：reveal.js 插件标准安装与启用阶段流程

1. 引入必要文件与样式表

除了 reveal.js 本身的基础文件 dist/reveal.css 与主题文件（如 dist/theme/black.css），高亮插件需要额外引入对应的高亮主题 CSS 文件。常用的高亮主题有 plugin/highlight/monokai.css 或 plugin/highlight/zenburn.css。在脚本层面，确保在页面底部引入 plugin/highlight/highlight.js 与 plugin/math/math.js。

2. 编写幻灯片语义标记

在 <div class="slides"> 容器内的各个 <section> 中，使用规范标记声明待解析内容。代码块必须以 <pre><code class="language-xxx"> 的结构组织；数学公式则根据是独立占行还是混排在段落中，分别使用 \[ ... \] 与 $ ... $。

3. 在初始化脚本中注册插件

reveal.js 通过 Reveal.initialize() 方法启动。通过向配置对象传入 plugins 数组参数，挂载 RevealHighlight 与 RevealMath.KaTeX（或 RevealMath.MathJax3）实例。

三、最小化完整集成模板

以下为一个可以直接在浏览器中打开并运行的完整 HTML 文件示例。示例中同时涵盖了带行号高亮的代码段落与标准的 LaTeX 微积分公式：

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>reveal.js 插件演示</title>
  <!-- reveal.js 核心与主题样式 -->
  <link rel="stylesheet" href="dist/reveal.css">
  <link rel="stylesheet" href="dist/theme/black.css">
  <!-- 代码高亮主题样式 (例如 Monokai) -->
  <link rel="stylesheet" href="plugin/highlight/monokai.css">
</head>
<body>
  <div class="reveal">
    <div class="slides">

      <!-- 第一页：代码高亮与按行切片 -->
      <section>
        <h3>代码高亮与分步聚焦</h3>
        <pre><code class="language-python" data-trim data-noescape data-line-numbers="1|3-4|6">
def calculate_energy(mass):
    # 光速常数 c
    c = 299792458
    energy = mass * (c ** 2)
    return energy
print(calculate_energy(1.0))
        </code></pre>
      </section>

      <!-- 第二页：LaTeX 数学公式渲染 -->
      <section>
        <h3>数学公式排版</h3>
        <p>爱因斯坦质能方程行内表示：$E = mc^2$</p>
        <p>高斯积分独立块级展示：</p>
        \[
          \int_{-\infty}^{+\infty} e^{-x^2} \, dx = \sqrt{\pi}
        \]
      </section>

    </div>
  </div>

  <!-- 引入核心脚本与插件脚本 -->
  <script src="dist/reveal.js"></script>
  <script src="plugin/highlight/highlight.js"></script>
  <script src="plugin/math/math.js"></script>

  <script>
    Reveal.initialize({
      // 开启历史记录支持
      hash: true,
      // 注册代码高亮与 KaTeX 数学公式插件
      plugins: [
        RevealHighlight,
        RevealMath.KaTeX
      ],
      // 可选：针对 KaTeX 自定义配置选项
      katex: {
        version: 'latest',
        delimiters: [
          { left: '$$', right: '$$', display: true },
          { left: '$', right: '$', display: false },
          { left: '\\[', right: '\\]', display: true },
          { left: '\\(', right: '\\)', display: false }
        ],
        ignoredTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
      }
    });
  </script>
</body>
</html>

四、关键属性与特性配置深度解析

为了在演讲演示中获得专业级的呈现质感，必须掌握高亮插件与公式插件的高级控制属性：

图 3：代码切片属性与公式渲染器特性对照

1. 代码行号分步聚焦技巧

在演讲时，如果一次性显示几十行代码，听众很容易失去焦点。reveal.js 的 data-line-numbers 属性支持强大的分步序列语法：

• data-line-numbers（无参数）：仅展示静态行号，不启用逐步聚焦。
• data-line-numbers="2"：默认高亮第 2 行，其他行暗色半透明。
• data-line-numbers="1,3,5"：离散高亮第 1、3、5 行。
• data-line-numbers="1-3|5-7|9"：以 | 划分为三个演示节拍。按向右翻页键时，焦点会在第一组行（1-3行）、第二组行（5-7行）和第三组行（9行）之间流畅过渡，而不会跳出当前幻灯片。

2. KaTeX 与 MathJax 的选型建议

reveal.js 内置了对 KaTeX、MathJax 2 与 MathJax 3 的多后端支持。在 Reveal.initialize 中通过 RevealMath.KaTeX 或 RevealMath.MathJax3 切换。在实际项目中，除非必须依赖极冷门的 LaTeX 宏定义，否则强烈建议优先选择 KaTeX，其纯客户端执行效率远高于 MathJax，能彻底杜绝翻页时公式“闪烁/重绘”的视觉迟滞感。

五、常见问题排查与全景速查矩阵

在集成过程中，初学者常会遇到格式冲突、路径错误或符号转义等典型问题。以下是排查指引：

图 4：三大核心异常特征与定位修复指引

常见排错细节说明

katex: {
  local: 'vendor/katex' // 指向本地存放 katex 资源的静态目录
}

六、集成要点总结

通过合理结合 RevealHighlight 的行级步进聚焦与 RevealMath 的高质量数学排版，演讲者能够在保持纯文本易维护性的同时，打造出兼具极佳交互体验与专业学术水准的现代化 HTML 演示文稿。