技术

让公式与流程图,成为解释的一部分

从一行公式到一张流程图和一段乐谱,演示 KaTeX、Mermaid 与 abcjs 在长文里的自然衔接。

本文目录

这是一篇功能演示,包含行内公式、块级公式、按需加载的 Mermaid 图表,以及用 ABC 记谱法写成的乐谱。

一行公式,有时胜过一段话

设输入为 xx,线性模型可以写成 y=wx+by = wx + b。行内公式应该与文字保持自然的基线,而不是打断阅读。

对于一组样本,可以用均方误差描述预测与真实值之间的距离:

L(w,b)=1n∑i=1n(yi−(wxi+b))2L(w,b) = \frac{1}{n}\sum_{i=1}^{n}\left(y_i - (wx_i+b)\right)^2

公式在构建阶段排版,不需要等待客户端计算。

把发布流程画出来

下面的图表只在接近可视区域时加载渲染器。关闭 JavaScript 时,仍然保留可读的源码。

flowchart LR
  A[写作 Markdown] --> B[内容校验]
  B --> C[静态页面]
  C --> D[搜索索引]
  D --> E[Cloudflare Pages]

主题切换

图表与页面共用明暗模式。浅色环境采用柔和底色,深色环境保持文字与连接线的可辨识度。

一段乐谱

五线谱用 ABC 记谱法书写,由 abcjs 在浏览器里排成 SVG。和图表一样,只有滚动到附近才会加载渲染器。

X:1
T:示例小曲
C:主题演示
M:4/4
L:1/4
K:D
A2 F2 | G2 E2 | D2 F2 | E4 |
A2 F2 | G2 E2 | D2 E2 | D4 |

主题切换时乐谱会跟着重画,音符与谱线都取当前文字颜色,所以在深色底上依然清楚。

图表也需要克制

当一段简单的文字已经足够,就不必再画图。当关系比顺序更重要时,图表才真正有帮助。

判断标准可以更具体一点:如果内容里有分支、并行或反馈回路,图表通常省下的是读者的时间;如果只是一串先后发生的步骤,一段编号列表更短也更好检索。公式同理——一次推导值得写出中间步骤,一个众所周知的结论直接引用就好。

搜索