2025年11月17日星期一
让 KaTeX 数学公式随处清晰可读
数学公式在知识库里通常依赖 KaTeX 或 LaTeX 才能优雅呈现，可一旦离开熟悉的 Markdown 编辑器，格式就可能被压扁。这篇笔记把“写 → 导出 → 存档 → 复用”的流程拆解成可复制的清单，让任何人都能把 KaTeX 公式整理成随处可读的素材，同时保留原始 Markdown 便于后续修改。
- 跨平台稳定性：会议纪要、企业邮箱、移动端 IM 常常禁止内嵌 HTML/MathML。发一张 PNG/SVG，接收方不需额外插件就能看到完整公式。
- 无障碍需求：教师或技术文档团队可以在 Markdown 中写出完整语义，再给图片补充 alt 文本，既满足屏幕阅读器，也满足视觉呈现。
- 版本管理方便：Markdown 仍然是文本，照常进入 Git/Directus 版本历史；图片只在发布端使用，不怕误改源文件。
- 命名规范：在标题或注释里注明“Lesson3_Quadratic_Roots”，日后检索超快。
- 行内与块级：短表达式
$F=ma$直接嵌入；推导或矩阵必须用$$…$$，否则窄屏会把行距压扁。 - 结构化注释：
<!-- topic: calculus / step: integration -->既能提示译者，也方便搜索。 - 排版余地：对包含根号、长分数的式子，刻意加空格或换行，保证在 600px 宽的预览里依旧清晰。
- Preset 选择：浅灰或米色背景 + Serif 字体能让阶梯式分数更易读；若是夜间主题，记得调大对比度。
- 字号与行距：字号 28px 左右最适合幻灯片截图；行距设在 1.45~1.6，可避免
\sqrt{}与下一行挤在一起。 - 分栏与留白：一次展示多条公式时，用
---分隔或利用 Markdown2Image 的组块组件，别让读者用眼疲劳。 - 导出格式：
- PNG：培训群、PPT、微信公众号常用，兼容性好。
- SVG：印刷、高清 PDF、响应式官网首选，放大不糊。
- WebP：体积小，适合需要快速加载的学习平台。
<!-- lesson: algebra / module: quadratic -->
二次方程求根公式：
$$
x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}
$$
其中 $a \\neq 0$，且判别式 $\\Delta = b^2-4ac$ 决定根的个数与类型。
导出后在 Markdown2Image 的“注释”一栏填写：
- Alt 文本：
Quadratic formula for ax^2+bx+c=0 - Caption：
《代数基础》第 3 讲示例
- Alt 文本：描述式子的用途，例如“求解抛物线顶点的公式”。
- Caption 模板：
图 n-1｜主题 + 场景，例如“图 2｜金融数学-复利推导”。 - 标签与分类：在 Directus 中使用
topic: algebra、grade: high-school等自定义字段，跨项目检索效率翻倍。 - 文件命名：
katex_quadratic_formula_light.png、katex_quadratic_formula.svg等语义化命名会让设计团队感激你。
- 存储结构：在 Directus 里建立“公式素材库”集合，字段包含 Markdown、语言、图片文件、用途说明。
- 审批流程：先在测试环境检查导出的图片尺寸与可访问性，再提交内容审核，避免生产环境反复回滚。
- 翻译与本地化：
- Markdown 部分交给翻译同事；公式主体通常通用，仅需留意符号注释与背景说明。
- 图片 caption 若含本地化文案，可在 Markdown2Image 中开启多语言模板，一次导出多份。
- 复用策略：在内部 Wiki 写明“先搜索素材库、若无再创建”，避免相似公式重复生产。
- Markdown 中的 KaTeX 渲染正确（可在预览窗口手动检查）。
- 图片版本没有锯齿；手机预览也能一屏读完。
- Alt 文本、Caption、标签填写完整。
- PNG 和 SVG 命名统一并同步上传。
- Markdown 与图片在 Directus 中互相引用，任何人打开条目即可下载两者。
| 症状 | 可能原因 | 处理方式 |
|---|---|---|
| 根式被截断 | 行距过小或未开启“保持比例” | 调整行距，或在 \sqrt{} 外增加 \, 防止紧贴 |
| 邮件中模糊 | PNG 分辨率过低 | 导出 2 倍分辨率或改用 SVG |
| 翻译后丢失上下文 | 缺少注释和元数据 | 在 Markdown 加注释，Directus 中写清“课程/章节” |
| 学生复制不了源码 | 只提供了图片 | 图片旁附上 KaTeX 片段或提供下载链接 |
最后一步是告诉团队“公式素材已经在 Directus 的 math_assets 集合里”。同时把 Markdown2Image 的导出设置打包成模板（例如“KaTeX-淡色”、“KaTeX-深色”），让其他老师或工程师只需粘贴公式即可获取统一风格的图片。
完成这一套流程后，你就拥有：
- 可迭代的 KaTeX Markdown——随时修订、翻译、版本管理。
- 兼容任何载体的图片——会议、教材、博客、推送都能直接用。
- 明确的协作规范——资料去哪找、怎样命名、如何更新都有了答案。
这就是把数学内容从“只能在少数编辑器里正确显示”升级到“放到哪里都干净利落”的关键一步。