做学术报告和课堂讲义的人，多半经历过同一个尴尬场面：PPT做了一版，讲义单独维护一版，遇到公式修改，两边同步改，改完格式又乱了。我第一次看到hyperframes这个开源项目时，最大的触动就是它把这条烂路彻底绕开了。hyperframes 是一套开源的 HTML 演示与文档框架，作者是长期从事统计教学的研究者，核心思路是用同一份源文件同时产出网页幻灯片、可打印讲义和 PDF 文档，而且公式、代码、图表都能原生渲染。它适合三类人：经常做数学或统计类演示的教师、需要把学术报告和论文格式统一的研究者，以及想用轻量方案搭建个人技术分享页面的程序员。这篇文章我会从安装、模板机制、样式定制一直讲到实际踩过的坑，尽量把能直接复现的步骤都放进来。

1. hyperframes 到底解决的是什么事

1.1 传统演示工具里最隐蔽的成本：双份维护

先说痛点。我自己最早用 PowerPoint 做统计课课件，公式用 MathType 敲，图表从 R 里导出图片再贴进去。一学期下来，课件文件 200 多 MB，讲义是另一份 Word 文档，内容七八成重复，但排版完全不同。每次调整一个参数，要改图、改公式、改文字，再手动把讲义同步一遍。这种"双份维护"的成本是隐性的——它不会让你当场崩溃，但会在每个深夜赶材料的时候反复折磨你。

后来换到 LaTeX + Beamer，公式问题解决了，但 Beamer 的幻灯片风格偏老气，想改个配色要翻几十页文档，而且讲义仍然要单独写一个版本。最关键的是，Beamer 编译一次要跑好几遍 LaTeX，图表一多，等待时间长到可以泡杯咖啡。hyperframes 的处理方式完全不同：它不把幻灯片当成"PPT"来设计，而是把每一页当成一个独立的 HTML 页面，用浏览器来展示，屏幕上的效果就是网页效果，打印稿就是网页的打印版。

1.2 一套源文件，三种产出的设计逻辑

hyperframes 的核心设计可以总结成一句话：内容是 HTML 片段，样式是 CSS，公式是 MathJax，动态效果是 JavaScript。你写内容的时候不用关心最终是幻灯片还是讲义，只要把每一页的内容写清楚，框架会自动在浏览器里拼装成完整的演示文稿。

它和常见工具的关系也很有意思。hyperframes 兼容 R Markdown 工作流，你可以直接用 Markdown 写内容，代码块由 knitr 执行并把结果嵌入页面；同时它也接受纯 HTML 作为基本输入。这意味着三种产出可以这样得到：

• 幻灯片模式：浏览器全屏翻页，支持键盘方向键、触屏滑动，适合现场演示。
• 讲义模式：同一份内容，通过切换打印样式，所有页面按顺序平铺打印出来，适合发给学生或听众。
• PDF 文档：在浏览器里直接打印输出 PDF，或者通过 pandoc 转到 LaTeX 再生成正式的 PDF 文档。

我在实际使用中最喜欢的一点是，源文件里每一页就是一个<section>块，不需要像 Beamer 那样记忆一堆命令。写内容的心情和写网页一样，顺手。

提示：如果你之前用 Markdown 写笔记，上手 hyperframes 几乎没有学习成本；如果你只会 PPT，第一天会不太习惯"用 HTML 写幻灯片"这个思路，但坚持两三天就能感受到效率提升。

2. 半小时跑通第一份 hyperframes 演示

2.1 环境准备：RStudio 方案和纯命令行方案怎么选

hyperframes 的依赖并不复杂，但根据你的使用习惯，有两种起步路径。

方案 A：RStudio + R Markdown（推荐给统计/教学场景）

如果你平时会用到 R 做数据分析，这个方案最顺畅。需要安装 R 和 RStudio，然后安装 rmarkdown 包，再安装 hyperframes 对应的 R 包。装好之后，RStudio 的新建文件模板里会出现 hyperframes 相关的幻灯片模板，直接点击就能生成一个带示例的工程。

方案 B：纯静态文件 + 任意编辑器（推荐给前端/纯文档场景）

直接从 GitHub 仓库 Clone 项目到本地，里面的example或demo目录就是完整的演示样例。你不需要安装任何软件，浏览器打开生成的 HTML 文件就能看效果。想改内容就编辑对应的 HTML 文件，改完刷新浏览器即可。这个方案对系统没有要求，Windows、macOS、Linux 都可以。

我自己是 A 和 B 混着用的：快速测试用方案 B，正式课件和报告用方案 A。环境准备的时间大约 15 分钟，主要花在安装 R 包上。

2.2 最小示例：一个三页的幻灯片

不管用哪种方案，hyperframes 的内容核心都是 HTML 片段。下面这个例子展示的是三个页面，纯 HTML 形式：

<section> <h1>第一页：标题页</h1> <p>这里写副标题、作者和日期。</p> </section> <section> <h2>第二页：列出要点</h2> <ul> <li>要点一</li> <li>要点二</li> <li>要点三</li> </ul> </section> <section> <h2>第三页：嵌入公式</h2> <p> 欧拉公式： \[ e^{i\pi} + 1 = 0 \] </p> </section>

如果是 R Markdown 场景，内容更接近 Markdown：

--- title: "我的第一份演示" output: hyperframes::html --- # 第一页：标题页 这里写副标题、作者和日期。 # 第二页：列出要点 - 要点一 - 要点二 - 要点三 # 第三页：嵌入公式 欧拉公式： \[ e^{i\pi} + 1 = 0 \]

编译的方式很简单：RStudio 里点一下 Knit 按钮；纯 HTML 方式则直接在浏览器打开。如果幻灯片没有自动全屏，按 F11 或者用项目自带的控制按钮进入演示模式。

2.3 目录结构里藏着哪些门道

第一次打开仓库时，我建议你重点看这几个目录：

• 内容目录：里面放的是每一页的内容文件。你可以一个页面一个文件，也可以把所有页面放在一个文件里，框架会按顺序拼接。
• 样式目录：放全局 CSS 和 JavaScript。所有页面的外观都由这里控制，配色、字体、动画都在这个目录里改。
• 输出目录：编译后生成的 HTML 文件在这里。浏览器直接打开的是这个目录下的文件。

最初我没搞懂"一个页面一个文件"的拼接逻辑，以为要自己写脚本合并，后来发现框架已经做了这个工作。你只要把页面文件放进指定目录，命名成01.html、02.html这样的顺序，框架在构建时会自动生成一个带侧边栏导航的总文件。这个设计尤其适合多人协作，比如一个团队每人负责一页，各自编辑自己的文件，互不干扰。

3. 核心机制拆解：页面如何变成演示文稿

3.1 每一页都是一个 frame，翻页就是切换 frame

hyperframes 里有一个核心概念叫frame，也就是"帧"。你可以把整个幻灯片理解成一部动画片的胶片，每一帧是一个独立的画面。框架在网页上做的事，其实就是在这些 frame 之间做切换。

具体到 HTML 结构，一个<section>就是一张幻灯片页面。框架会给每个 section 分配一个编号，浏览器地址栏里的#1、#2就对应第几页。这个设计带来了两个直接好处：

第一，分享位置非常精确。你想让同事直接看到第 7 页，把带#7的链接发过去就行，对方打开浏览器会直接跳到那一页，不需要翻页。PPT 要精确分享某一页得"另存为单页文件"，这个功能省了不少事。

第二，刷新页面后自动回到当前页。演示到一半浏览器崩溃，重新打开链接，它会自动定位到你崩溃前的位置。对于现场讲课的人来说，这个体验简直救命。

翻页支持键盘左右方向键、空格键、PageUp/PageDown，触屏设备上支持左右滑动。框架还默认支持全屏模式，讲课的时候可以让内容占满整个屏幕，学生后排也看得清。

3.2 公式、代码和图表是怎么嵌进去的

学术演示绕不开数学公式。hyperframes 用的是 MathJax 渲染 LaTeX 格式的公式，所以你只要按 LaTeX 的语法写公式，页面加载时会自动渲染成矢量公式，放大缩小都不会糊。

代码高亮方面，框架自带一套代码高亮方案。你只需要在 HTML 里把代码包在<pre><code>标签里，框架会按语言语法上色。从我的实际使用经验看，它支持的常见语言包括 C、Python、R、JavaScript、Shell 等，够用。

如果通过 R Markdown 方式使用，还有一个隐藏优势：代码块可以直接执行。举例来说，我想在某一页展示mtcars数据集的回归结果，只需要在 Markdown 里写：

```{r, echo=TRUE} summary(lm(mpg ~ wt, data = mtcars)) ```

编译的时候，knitr 会先执行这段代码，再把结果以格式化文本或图表的形式嵌入到页面里。这意味着你幻灯片里的数字永远和代码输出一致，不会出现"截图里的结果和后来重跑的结果对不上"这种事。

3.3 用 CSS 和 JavaScript 改出专属风格

很多人用 Beamer 最头疼的就是改风格，hyperframes 在这方面几乎是"降维打击"——你直接改 CSS 就行。所有页面的外观都由样式文件控制，几个常用变量改一改，整套风格就变样。

比如想换主导色，找到样式文件里的颜色定义，像这样：

:root { --main-color: #2c3e50; --accent-color: #e74c3c; --background: #fdf6e3; }

改完刷新浏览器，全部页面的配色统一变化。想加自己的 logo，在页面模板里加一个<img>标签，再通过 CSS 固定到角落就行。我在做系列课程时，把每个章节的主题色改成不同颜色，学生一眼就能看出切换到了新章节，视觉引导效果比 PPT 的自带主题强多了。

JavaScript 部分则可以做更高级的交互。hyperframes 暴露了页面切换的事件接口，简单来说，当用户翻到某一页，你可以触发一个自定义动作。我试过在章节页自动播放一段动画，在总结页自动弹出一个小测验的提示框，效果都挺稳定。有一点要提醒：如果只是做教学演示，交互别太多，翻页卡顿和被花哨效果分散注意力都是实际踩过的坑。

注意：改样式的时候尽量只改属于内容层的 CSS 类，不要动框架的核心布局代码。我最初为了调一个间距，不小心改了底层模板，结果所有页面的标题都错位了。框架的原始文件最好留一份备份。

4. 实战场景：讲义、学术报告和个人站点

4.1 课堂讲义的一鱼三吃

我这里说的"一鱼三吃"，是指同一份内容，能同时产出上课用的幻灯片、课后复习用的讲义、以及单元测验的题目页。

幻灯片的逻辑是"一屏一页"，所以内容要精炼，每页只讲一个主题。讲义的逻辑是"纸面阅读"，所以需要把每页内容按顺序平铺，同时补充一些课上口头讲的衔接说明。hyperframes 在这个场景下的做法是：内容不变，只换一套打印样式。

具体到操作上，我会在打印样式表里加上@media print规则，让打印版本自动隐藏上一页/下一页按钮，去掉动画元素，把每个 frame 的间距拉大，并显示页码。学生拿到的讲义是一个结构清晰、可直接打印的 PDF，而我自己讲课用的仍是同一份源文件做成的幻灯片。

遇到需要出单元测验的时候，这个模式的效率更明显。我在源文件里加入隐藏的题目 section，平时演示模式下不显示，打印时通过样式显示出来，一套题目的初稿十分钟就能搞定。当然，题目的专业性和严谨性仍然要靠人工保证，框架只解决"三份材料格式统一"的问题。

4.2 学术报告和论文引用怎么处理

学术报告通常要求公式规范、引用清楚。hyperframes 对引用的支持方式比较灵活：如果你用 R Markdown 工作流，可以直接调用 BibTeX 文件管理参考文献，正文里按标准语法引用，编译后会自动生成参考文献列表和链接。这在写方法论部分时特别省心，因为论文里的引用和幻灯片里的引用可以共用同一个 BibTeX 文件。

公式的编号需求，hyperframes 也能满足。你可以给公式加标签和编号，形式跟在 LaTeX 里很像：

<p> 重要公式： \[ \hat{\beta} = (X^\top X)^{-1} X^\top y \] (1) </p>

需要导出正式 PDF 的时候，可以在浏览器里用打印功能保存，也可以走 pandoc 转 LaTeX 的路线。两种方式我都跑过，简单场景直接浏览器打印更快；要求严格的期刊排版，建议还是从 LaTeX 管道输出，再手工微调。

4.3 把 hyperframes 用成个人技术展示页面

如果你不讲课也不做学术，hyperframes 照样有用。因为它本质上是网页，所以你可以把它当作一个极简的个人项目展示站点。

我做过一个内部工具的介绍页，用 hyperframes 把功能截图、命令行示例和架构说明组织成几页，部署到静态托管服务上，组内成员打开链接就能看。相比写一份长文档，这方式更像"有人带着你过一遍"，阅读体验好不少。而且因为是静态 HTML，不需要服务器动态渲染，部署成本几乎为零。

用 iframe 把 hyperframes 页面嵌入博客或者文档站里也很方便。一篇教程文章里嵌一个可交互的演示文稿，读者可以边读边点，比贴大段代码更直观。我目前的一个内部数据规范文档，就是用这种方式嵌在团队 Wiki 里的。

5. 常见问题与排查技巧实录

5.1 编译报错：先从依赖和版本查起

用 hyperframes 最常见的问题是编译过程中出现各种报错，以 R Markdown 场景居多。表格整理了几种高频场景和排查思路：

我自己的习惯是：报错之后先不要怀疑框架，先怀疑数据和依赖。有几次报错，本质上都是某个 R 包在新版本里改了函数名，跟 hyperframes 一点关系都没有。

5.2 中文显示与字体的坑

中文用户最容易遇到两个坑：一是浏览器里中文显示为方框，二是打印出的 PDF 中文乱码或字体难看。

浏览器里显示方框，基本是字体问题。检查页面 CSS 里是否显式指定了中文字体，如果没有，添加类似下面的规则：

body { font-family: "Noto Sans CJK SC", "PingFang SC", "Microsoft YaHei", sans-serif; }

如果是通过 R Markdown + LaTeX 导出的 PDF，情况会稍复杂。LaTeX 默认字体不支持中文，需要配置CJKmainfont，例如用 xelatex 引擎编译时，在 YAML 头里指定：

output: pdf_document: latex_engine: xelatex includes: - header.tex

在header.tex里写上：

\usepackage{xeCJK} \setCJKmainfont{Noto Sans CJK SC}

这套组合实测下来比较稳。如果你没有安装中文字体，先用fc-list :lang=zh（Linux/macOS）确认系统中存在哪些可用字体，选一个换上就好。

5.3 图片、视频和文件路径的坑

hyperframes 项目里页面文件可能和总文件不在同一个目录，这会导致相对路径失效。最典型的情况是：页面里写了一幅图片，单独看页面文件时图片能显示，但编译成整个演示文稿后图片变成了碎图。

原因很简单：图片路径是相对于内容文件所在目录写的，而最终展示时路径是相对于输出目录解析的。解决的思路有两种，第一，统一把图片放到一个全局静态目录，然后用绝对路径引用；第二，在内容里用相对输出目录的路径。我推荐第一种，省心。

视频自动播放也是个常见的期待。如果想在某一页嵌入教学视频并让它自动播放，需要在视频标签里加autoplay和muted两个属性：

<video autoplay muted loop> <source src="video/demo.mp4" type="video/mp4"> </video>

但需要注意，移动端浏览器的自动播放策略各不一样，很多情况下仍然需要用户手指点一下才播放。现场演示时最好留一手，比如页面下方放一个手动播放按钮，避免站在台上等视频加载的尴尬。

5.4 打印与 PDF 导出的页边距问题

从浏览器打印 hyperframes 页面时，默认的打印样式未必能直接套用。如果发现打印出来的页码不对或者内容被截断，建议在打印样式表里明确设置分页规则。比如，让每一页内容单独成一页：

@media print { section.frame { page-break-after: always; margin: 2cm; } }

打印页的页眉页脚信息，也可以通过浏览器的打印设置来控制。Chrome 的打印对话框里可以关闭"页眉和页脚"，否则每页顶部都会带网址和日期，很不专业。我刚开始给学生出讲义的时候没关这项，学生手里每一页抬头都有网址，看起来真的很业余。

还有一个小技巧：如果需要讲义版 PDF 的边距统一，可以用 CSS 里的@page规则：

@page { size: A4; margin: 2.5cm 2cm; }

这样输出的 PDF 每一页边距都会统一，不会出现内容歪斜的问题。

6. 最后说几句实际的体会

用了几年 hyperframes，我最大的体会是：它不会替你写好内容，但会把你从"排版重复劳动"里彻底解放出来。以前做一份课件，真正花在思考教学逻辑上的时间可能只有三分之一，剩下都是调格式；现在只要把内容和结构写好，剩下的样式交给 CSS，编译交给框架，我能把更多精力放回内容本身。

如果你准备尝试，我的建议是：先照官方示例不改任何样式地跑一遍完整流程，确认幻灯片展示、打印、PDF 导出三个环节都通了，再开始改配色和字体。不要一上来就折腾定制，否则你分不清哪个阶段出的问题到底来自哪里。这个内容后续还可以继续扩展，比如给框架写自己的主题模板、和 CI 工具配合每次提交自动编译部署页面，都是很顺的方向。